Skip to main content
POST
Create Campaign

Authorizations

X-API-Key
string
header
required

Authenticate every request by passing your API key in the X-API-Key header. Keys are scoped to your organization hierarchy.

Headers

Idempotency-Key
string

Optional idempotency key: a unique string of 16-200 printable ASCII characters (a UUID is recommended). Retrying the write with the same key within 24 hours returns the stored response of the first call with an X-Idempotent-Replayed: true response header instead of executing it again. Reusing a key with a different request body returns 422 (IDEMPOTENCY_MISMATCH); a duplicate sent while the first call is still running returns 409 with a Retry-After header. Keys are scoped per endpoint and organization.

Required string length: 16 - 200

Body

application/json
name
string
required
Maximum string length: 255
sender_identity_id
string<uuid>
required
list_ids
string<uuid>[]
required
Required array length: 1 - 50 elements
suppression_list_ids
string<uuid>[]
Maximum array length: 50
template_id
string<uuid>
subject
string
Maximum string length: 255
preheader
string
Maximum string length: 255
html
string
Maximum string length: 1000000
source_code
string
Maximum string length: 255
refcode
string
Maximum string length: 255
append_utm
boolean

Append UTM parameters to outbound links for attribution.

is_repermission
boolean

Mark the send as a re-permission (re-consent) message.

tracking_domain_id
string<uuid> | null

Tracking domain serving this campaign's tracked links, open pixel, unsubscribe page and browser view, so recipients see your own links. host instead of the platform one. Must be an active tracking domain your organization owns or inherits from a parent. Omit to let the platform pick the obvious default (the tracking domain matching your sending domain's root, or your only one); send null to force the platform link host.

require_approval
boolean

Require an approval after the test send before this campaign can schedule or send. Off by default; every campaign still requires a successful test send regardless of this setting.

recipient_policy
enum<string>
default:max_reach

Which subscribed contacts on the campaign's lists actually receive it. max_reach (default) sends to every subscribed contact. max_deliverability sends only to contacts whose current validation verdict is deliverable; contacts that have never been validated are skipped.

Available options:
max_reach,
max_deliverability

Response

Campaign created.

success
boolean
required
data
object
required