A blast is a one-time send of an email to an audience. The typical workflow is:
Create a draft blast
Attach an audience with PUT .../audience
Attach an email with PUT .../email
Schedule it or send it now
Blast status moves through draft → scheduled → sending → sent, with failed, cancelled, and archived as side exits. The audience and email are only editable while the blast is a draft.
Reference an existing contact list, or create a new list and attach it in one call. This replaces any previously attached audience. Returns 200 OK with the updated blast object.
Dynamic audiences are defined by a rule tree of groups and conditions. Rule objects use camelCase keys, unlike the rest of the public API — they pass through to the segment engine verbatim.
field — a standard contact field key in camelCase (e.g. leadStatus, tentedScore, createdAt)
Per field type: strings take equals, not_equals, contains, not_contains, starts_with, ends_with; numbers and dates take equals, not_equals, greater_than(_or_equal), less_than(_or_equal); booleans take is_true, is_false. All types take is_empty / is_not_empty
custom_field
fieldDefinitionId — an active custom field definition ID
Groups combine children with operator: "and" (default) or "or" and can nest up to 5 levels deep, with at most 100 nodes per tree. Shorthand operator aliases (eq, neq, gt, gte, lt, lte, member_of, occurred, …) are accepted. email_step conditions are not allowed in audiences — they only work inside flow condition steps.
Reference an existing email with {"source": "existing", "email_id": "..."}, or create one inline:
Field
Type
Required
Notes
source
string
Yes
inline
name
string
No
Defaults to "<blast name> Email"
subject
string
No
1-998 characters. Must be set before the blast can send
template_id
uuid
No
Seed content and default headers from an approved template. Mutually exclusive with html
html
string
No
Seed content from your own HTML, up to 2 MB. Mutually exclusive with template_id
preview_text
string
No
Maximum 200 characters
from_name
string
No
Maximum 120 characters. Must be set before the blast can send
from_address
string
No
Must be set before the blast can send; domain must be verified
reply_to_email
string
No
Must be set before the blast can send
Omit both template_id and html for a blank branded scaffold. Returns 200 OK with the updated blast object.
The attached email must be approved before the blast can be scheduled or sent. Inline emails start as drafts — take the email.email_id from the response and approve it via POST /v1/emails/{emailId}/approve.
ISO-8601 datetime with timezone offset, e.g. 2026-07-10T09:00:00-07:00. Must be in the future
operational
boolean
No
Defaults to false — see below
Returns 200 OK with the blast in scheduled status. Use POST .../unschedule to cancel a scheduled send and return the blast to draft.
Setting operational: true marks the send as transactional: unsubscribed contacts are not suppressed and the unsubscribe footer is skipped. Only use it for non-marketing mail such as receipts and service notices.
Accepts the same optional operational flag and starts the send immediately through the async pipeline. Returns 202 Accepted with the blast in sending status; poll GET /v1/email-blasts/{blastId} for progress counters.
Page through a blast’s contacts by engagement category: recipients (everyone prepared for the send, the default), sent, delivered, opened, clicked, bounced, unsubscribed, or spam. Also accepts page, limit, search, sort (engagement *_at timestamps sort contacts without that event last), and order.Responses contain contacts and a pagination object:
PATCH /v1/email-blasts/{blastId} updates name and/or description.
POST /v1/email-blasts/{blastId}/archive archives a blast that is not mid-send.
DELETE /v1/email-blasts/{blastId} deletes it and returns {"blast_id": "...", "deleted": true}. Scheduled blasts must be unscheduled first, and archived blasts cannot be deleted.
