Skip to main content
POST
Create a new marketing campaign in draft status.

Authorizations

X-API-Key
string
header
required

Company API key - scoped to a specific company. Generate from the Integrations page in your dashboard.

Body

application/json

Campaign fields. Only name is required up front.

Request body for creating a marketing campaign. Only name is required; all other fields can be filled in later via PATCH or by calling /schedule or /send-now.

name
string
required

Internal campaign name

subject
string

Email subject line sent to recipients

fromName
string

Display name shown in the From: header

replyTo
string

Optional Reply-To email address. Must be a valid email if provided.

bodyHtml
string

HTML body of the email

senderProfileId
string

ID of the SequenceSenderProfile used to send this campaign

listId
string

ID of the smart list whose rows become recipients

fieldMappings
object

Field mapping for resolving recipient email from a list row, e.g. {"email": ["Email", "Work Email"]}

scheduleType
string

Schedule type (one of: now, scheduled). Default: now

scheduledAt
string

ISO timestamp at which to send (required when scheduleType is "scheduled")

timezone
string

IANA timezone name used to interpret scheduledAt

companyId
string

Company ID (falls back to the authenticated user's current company)

Response

The created marketing campaign (in draft status)

Marketing campaign object

id
string

Campaign ID

companyId
string

Company this campaign belongs to

uid
string

User ID that created the campaign

name
string

Internal campaign name

subject
string

Email subject line

fromName
string

Display name shown in the From: header

replyTo
string

Reply-To email address used on outgoing emails

bodyHtml
string

HTML body of the email

senderProfileId
string

Sender profile ID

listId
string

Smart list ID whose rows become recipients

fieldMappings
object

Field mapping for resolving recipient email from a list row

scheduleType
string

Schedule type (now, scheduled)

scheduledAt
string

ISO timestamp at which sending begins (for scheduled campaigns)

timezone
string

IANA timezone used to interpret scheduledAt

status
string

Campaign status (draft, scheduled, sending, sent, failed, cancelled)

sentCount
integer

Number of recipients the email has been sent to

failedCount
integer

Number of recipients that failed to send

skippedCount
integer

Number of list rows skipped (missing email, duplicate, etc.)

totalRecipients
integer

Total rows in the associated smart list at read time

startedAt
string

ISO timestamp when sending started

completedAt
string

ISO timestamp when sending completed

created_date
string

ISO timestamp when the campaign was created

updated_date
string

ISO timestamp when the campaign was last updated

smartList
object

Summary of the associated smart list

senderProfile
object

Summary of the sender profile