Skip to main content
POST
Create a campaign
Creates a draft campaign from html_content or a template_id. Send it with send a campaign now or schedule a campaign. Requires the campaigns:write scope. Not available to sandbox keys.

Authorizations

Authorization
string
header
required

API key for authentication

Headers

Idempotency-Key
string

A unique key for one logical campaign creation. Reuse it with the same payload when retrying. Keys are scoped to your team and retained for 24 hours.

Required string length: 1 - 255
Pattern: ^[A-Za-z0-9._-]{1,255}$

Body

application/json
name
string

Campaign name. Required unless subject is given, in which case the subject is used.

Maximum string length: 255
Example:

"October newsletter"

subject
string | null
Maximum string length: 998
Example:

"News for October"

from_email
string<email> | null
Maximum string length: 255
Example:

"news@example.com"

from_name
string | null
Maximum string length: 255
Example:

"Example"

reply_to
string<email> | null
Maximum string length: 255
html_content
string | null

Email HTML. Merge tags such as {{first_name}} are filled from contact properties. Cannot be combined with template_id; required when json_content is given.

Example:

"<p>Hello {{first_name}}</p>"

json_content
object | null

Editor JSON stored next to html_content so the campaign can be opened in the editor.

template_id
integer | null

Template from one of your projects. Its HTML is copied onto the campaign. Cannot be combined with html_content.

audience_config
object | null

Who receives the campaign. Lists and segments are combined (a contact in any of them receives it); topic_id further limits recipients to contacts subscribed to that topic. With no lists or segments, every subscribed contact receives it.

language_overrides
object | null

Per-language sender and subject overrides, keyed by language code.

Response

Campaign created successfully. A replay of an earlier request with the same Idempotency-Key returns the campaign that request created.

message
string
required
Example:

"Campaign created successfully."

data
object
required

Full campaign representation including rendered HTML content.