Campaigns

List campaigns

GET/api/v1/email/campaigns

GET /email/campaigns
curl -X GET 'https://www.unitpost.com/api/v1/email/campaigns' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "campaign",
      "id": "id_123",
      "name": "Example",
      "template_id": "template_123",
      "segment_id": "segment_123",
      "topic_id": "topic_123",
      "from": "you@yourdomain.com",
      "subject": "Welcome to Acme",
      "preview_text": "string",
      "open_tracking": false,
      "click_tracking": false,
      "status": "draft",
      "scheduled_at": "2026-01-01T00:00:00.000Z",
      "variable_fallbacks": {},
      "excluded_contact_ids": [
        "string"
      ],
      "total_recipients": 1,
      "projected_recipients": {
        "total": 1,
        "reachable": 0,
        "skipped": 0
      },
      "sent_count": 1,
      "failed_count": 1,
      "pause_reason": {
        "code": "user",
        "message": "string",
        "metric": "hard_bounce_rate",
        "value": 0,
        "threshold": 0,
        "sample": {
          "events": 0,
          "of": 0
        },
        "window": {
          "since": "string"
        },
        "decided_by": "floor",
        "resume": "self_serve",
        "paused_at": "2026-01-01T00:00:00.000Z"
      },
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Retrieve a list of your campaigns, cursor-paginated. Each row is a reference to one campaign and its current status (draft, scheduled, sending, sent, …). Use a campaign's id with Retrieve a campaign for the full record, or with List sent emails (?campaign_id=) to see the individual emails it produced. Deleted (archived) campaigns are hidden; pass ?archived=true to list only archived ones, which can be restored for 30 days. Requires the campaigns:read capability.

Parameters6 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
archivedboolean · queryWhen true, list only archived campaigns instead of active ones.
topic_idstring · queryOnly campaigns scoped to this topic. An id from another workspace or channel matches nothing.
segment_idstring · queryOnly campaigns aimed at this segment (`seg_…`).
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
template_idrequiredstring—
segment_idrequiredstring—
topic_idrequiredstring | null—
fromrequiredstring—
subjectrequiredstring | null—
preview_textrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
scheduled_atrequiredstring | null—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
total_recipientsrequirednumberRecipients the engine admitted when the campaign started sending. 0 while it is `draft` or `scheduled`: read `projected_recipients`, or `sendable` from validate.
projected_recipientsobject | nullThe audience counted when the campaign was sent or scheduled: `total` segment members, `reachable` who will get it, `skipped` (unsubscribed, suppressed, excluded). Null for a draft that was never sent: read validate. Read-only.
sent_countrequirednumber—
failed_countrequirednumber—
pause_reasonrequiredobject | null—
created_atrequiredstring—
updated_atrequiredstring—
200401422

Create a campaign

POST/api/v1/email/campaigns

POST /email/campaigns
curl -X POST 'https://www.unitpost.com/api/v1/email/campaigns' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "June newsletter",
    "subject": "What's new",
    "from": "you@yourdomain.com",
    "template_id": "tmpl_123",
    "segment_id": "seg_123"
  }'
Response · 201
{
  "object": "campaign",
  "id": "id_123",
  "name": "Example",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "topic_id": "topic_123",
  "from": "you@yourdomain.com",
  "subject": "Welcome to Acme",
  "preview_text": "string",
  "open_tracking": false,
  "click_tracking": false,
  "status": "draft",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "total_recipients": 1,
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "sent_count": 1,
  "failed_count": 1,
  "pause_reason": {
    "code": "user",
    "message": "string",
    "metric": "hard_bounce_rate",
    "value": 0,
    "threshold": 0,
    "sample": {
      "events": 0,
      "of": 0
    },
    "window": {
      "since": "string"
    },
    "decided_by": "floor",
    "resume": "self_serve",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Create a campaign in draft. Target either a saved segment (segment_id, see Create a segment) or an inline recipients list of up to 5,000 addresses (a list you keep in your own system needs no import: the addresses become contacts, so an unsubscribe is remembered), and optionally scope it to a subscription topic (topic_id) so contacts who opted out of that topic are skipped automatically. Content comes from a published template_id (campaigns have no inline html/text). Set scheduled_at (ISO 8601 with Z or an offset such as 2026-10-27T08:00:00-07:00; stored and returned in UTC; inside your plan's scheduling window, at most 90 days) to save a send time. Without one, or once it has passed, the campaign goes out the moment you send it (validate warns SCHEDULE_PASSED). Nothing is sent yet — edit the draft with Update a campaign, check it with Validate a campaign, then launch it with Send a campaign. Requires the campaigns:write capability.

Request body13 fields
FieldTypeDescription
namerequiredstring—
template_idrequiredstring—
segment_idstring—
recipientsstring[]—
topic_idstring—
fromrequiredstring—
subjectstring—
preview_textstring—
scheduled_atstringISO 8601 with `Z` or a `±hh:mm` offset; normalized to UTC (reads return the UTC time). A time without a timezone, a bare date, or natural language is a `422`.
open_trackingboolean | null—
click_trackingboolean | null—
variable_fallbacksobject—
excluded_contact_idsstring[]—
Response · 201 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
template_idrequiredstring—
segment_idrequiredstring—
topic_idrequiredstring | null—
fromrequiredstring—
subjectrequiredstring | null—
preview_textrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
scheduled_atrequiredstring | null—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
total_recipientsrequirednumberRecipients the engine admitted when the campaign started sending. 0 while it is `draft` or `scheduled`: read `projected_recipients`, or `sendable` from validate.
projected_recipientsobject | nullThe audience counted when the campaign was sent or scheduled: `total` segment members, `reachable` who will get it, `skipped` (unsubscribed, suppressed, excluded). Null for a draft that was never sent: read validate. Read-only.
sent_countrequirednumber—
failed_countrequirednumber—
pause_reasonrequiredobject | null—
created_atrequiredstring—
updated_atrequiredstring—
201401403404409422

Retrieve a campaign

GET/api/v1/email/campaigns/{id}

GET /email/campaigns/{id}
curl -X GET 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "campaign",
  "id": "id_123",
  "name": "Example",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "topic_id": "topic_123",
  "from": "you@yourdomain.com",
  "subject": "Welcome to Acme",
  "preview_text": "string",
  "open_tracking": false,
  "click_tracking": false,
  "status": "draft",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "total_recipients": 1,
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "sent_count": 1,
  "failed_count": 1,
  "pause_reason": {
    "code": "user",
    "message": "string",
    "metric": "hard_bounce_rate",
    "value": 0,
    "threshold": 0,
    "sample": {
      "events": 0,
      "of": 0
    },
    "window": {
      "since": "string"
    },
    "decided_by": "floor",
    "resume": "self_serve",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Retrieve a single campaign by id, including its status, targeting, content references, and schedule. To see the individual emails a sent campaign produced, filter List sent emails by campaign_id; for a pre-send readiness report, use Validate a campaign. Requires the campaigns:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
template_idrequiredstring—
segment_idrequiredstring—
topic_idrequiredstring | null—
fromrequiredstring—
subjectrequiredstring | null—
preview_textrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
scheduled_atrequiredstring | null—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
total_recipientsrequirednumberRecipients the engine admitted when the campaign started sending. 0 while it is `draft` or `scheduled`: read `projected_recipients`, or `sendable` from validate.
projected_recipientsobject | nullThe audience counted when the campaign was sent or scheduled: `total` segment members, `reachable` who will get it, `skipped` (unsubscribed, suppressed, excluded). Null for a draft that was never sent: read validate. Read-only.
sent_countrequirednumber—
failed_countrequirednumber—
pause_reasonrequiredobject | null—
created_atrequiredstring—
updated_atrequiredstring—
200401404

Update a campaign

PATCH/api/v1/email/campaigns/{id}

PATCH /email/campaigns/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "campaign",
  "id": "id_123",
  "name": "Example",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "topic_id": "topic_123",
  "from": "you@yourdomain.com",
  "subject": "Welcome to Acme",
  "preview_text": "string",
  "open_tracking": false,
  "click_tracking": false,
  "status": "draft",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "total_recipients": 1,
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "sent_count": 1,
  "failed_count": 1,
  "pause_reason": {
    "code": "user",
    "message": "string",
    "metric": "hard_bounce_rate",
    "value": 0,
    "threshold": 0,
    "sample": {
      "events": 0,
      "of": 0
    },
    "window": {
      "since": "string"
    },
    "decided_by": "floor",
    "resume": "self_serve",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Edit a campaign while it's still in draft (edits after that return 409; unschedule a scheduled one first with Unschedule a campaign). Change its name, subject, from, preview_text, template_id or segment_id (a template or segment gets create's checks: this workspace's, published, not archived). A value equal to the draft's is no edit, so you can send back what you read. Beyond content and targeting, you can: send archived to archive/restore it; set variable_fallbacks (fill-only per-variable defaults) and/or excluded_contact_ids to resolve a send blocked by missing variables — the API equivalent of the dashboard's pre-send fix; set topic_id to scope it to a subscription topic (or null to clear); set open_tracking/click_tracking (tri-state; null inherits the template/domain default); and set or clear (null) the saved scheduled_at (a misnamed time key is a 422). Other keys are ignored. See what's blocking a send with Validate a campaign. Requires the campaigns:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body13 fields
FieldTypeDescription
archivedboolean—
namestring—
template_idstring—
segment_idstring—
fromstring—
subjectstring | null—
preview_textstring | null—
topic_idstring | null—
open_trackingboolean | null—
click_trackingboolean | null—
variable_fallbacksobject—
excluded_contact_idsstring[]—
scheduled_atstring | null—
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
template_idrequiredstring—
segment_idrequiredstring—
topic_idrequiredstring | null—
fromrequiredstring—
subjectrequiredstring | null—
preview_textrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
scheduled_atrequiredstring | null—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
total_recipientsrequirednumberRecipients the engine admitted when the campaign started sending. 0 while it is `draft` or `scheduled`: read `projected_recipients`, or `sendable` from validate.
projected_recipientsobject | nullThe audience counted when the campaign was sent or scheduled: `total` segment members, `reachable` who will get it, `skipped` (unsubscribed, suppressed, excluded). Null for a draft that was never sent: read validate. Read-only.
sent_countrequirednumber—
failed_countrequirednumber—
pause_reasonrequiredobject | null—
created_atrequiredstring—
updated_atrequiredstring—
200401403404409422

Delete a campaign

DELETE/api/v1/email/campaigns/{id}

DELETE /email/campaigns/{id}
curl -X DELETE 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

Archive a campaign that's in draft or a terminal state (sent, canceled, failed): it leaves the list and is permanently deleted after 30 days. Restore it before then with PATCH { "archived": false }. A campaign that's mid-flight can't be archived — stop it first with Cancel a campaign. Requires the campaigns:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
204401404409

Send a campaign

POST/api/v1/email/campaigns/{id}/send

POST /email/campaigns/{id}/send
curl -X POST 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/send' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "campaign",
  "id": "id_123",
  "name": "Example",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "topic_id": "topic_123",
  "from": "you@yourdomain.com",
  "subject": "Welcome to Acme",
  "preview_text": "string",
  "open_tracking": false,
  "click_tracking": false,
  "status": "draft",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "total_recipients": 1,
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "sent_count": 1,
  "failed_count": 1,
  "pause_reason": {
    "code": "user",
    "message": "string",
    "metric": "hard_bounce_rate",
    "value": 0,
    "threshold": 0,
    "sample": {
      "events": 0,
      "of": 0
    },
    "window": {
      "since": "string"
    },
    "decided_by": "floor",
    "resume": "self_serve",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Validate a draft campaign and then send it now or schedule it. scheduled_at in the body schedules it for that time (ISO 8601 with Z or an offset; in the future, inside your plan's scheduling window); null sends it now; omit it to use the draft's saved scheduled_at while that is still in the future — **otherwise the campaign is sent immediately** (except right after a dashboard Unschedule, which cleared its time: then it answers 409 with details[].code send_time_required and sends nothing, so name the time or pass null). The response's scheduled_at is the resolved time in UTC (null when it is sending now). A misnamed time field (scheduledAt, send_at, deliver_at, …) is a 422 naming scheduled_at, and a body that isn't JSON (a form-encoded one included) is a 400; nothing is sent in either case. Other fields are ignored and a JSON null body means no options. If anything blocks the send (unverified domain, missing template variables, empty audience, …) you get a 409 with each blocking reason itemized in error.details[] (code is the reason, as in the validate report's blockers[].code). To see the full pre-send report without attempting a send, use Validate a campaign; fix variable issues via Update a campaign. A launched campaign can be paused or canceled, and a scheduled one rescheduled. Requires the campaigns:send capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body1 field
FieldTypeDescription
scheduled_atstring | null—
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
template_idrequiredstring—
segment_idrequiredstring—
topic_idrequiredstring | null—
fromrequiredstring—
subjectrequiredstring | null—
preview_textrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
scheduled_atrequiredstring | null—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
total_recipientsrequirednumberRecipients the engine admitted when the campaign started sending. 0 while it is `draft` or `scheduled`: read `projected_recipients`, or `sendable` from validate.
projected_recipientsobject | nullThe audience counted when the campaign was sent or scheduled: `total` segment members, `reachable` who will get it, `skipped` (unsubscribed, suppressed, excluded). Null for a draft that was never sent: read validate. Read-only.
sent_countrequirednumber—
failed_countrequirednumber—
pause_reasonrequiredobject | null—
created_atrequiredstring—
updated_atrequiredstring—
200400401402403404409422429502503

Cancel a campaign

POST/api/v1/email/campaigns/{id}/cancel

POST /email/campaigns/{id}/cancel
curl -X POST 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/cancel' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "campaign",
  "id": "id_123",
  "name": "Example",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "topic_id": "topic_123",
  "from": "you@yourdomain.com",
  "subject": "Welcome to Acme",
  "preview_text": "string",
  "open_tracking": false,
  "click_tracking": false,
  "status": "draft",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "total_recipients": 1,
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "sent_count": 1,
  "failed_count": 1,
  "pause_reason": {
    "code": "user",
    "message": "string",
    "metric": "hard_bounce_rate",
    "value": 0,
    "threshold": 0,
    "sample": {
      "events": 0,
      "of": 0
    },
    "window": {
      "since": "string"
    },
    "decided_by": "floor",
    "resume": "self_serve",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Cancel a draft, scheduled, or sending campaign. Cancelation is terminal — the campaign can't be restarted afterwards. Messages already sent to recipients are not recalled. If you only want to stop temporarily, use Pause a campaign instead. Requires the campaigns:send capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
template_idrequiredstring—
segment_idrequiredstring—
topic_idrequiredstring | null—
fromrequiredstring—
subjectrequiredstring | null—
preview_textrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
scheduled_atrequiredstring | null—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
total_recipientsrequirednumberRecipients the engine admitted when the campaign started sending. 0 while it is `draft` or `scheduled`: read `projected_recipients`, or `sendable` from validate.
projected_recipientsobject | nullThe audience counted when the campaign was sent or scheduled: `total` segment members, `reachable` who will get it, `skipped` (unsubscribed, suppressed, excluded). Null for a draft that was never sent: read validate. Read-only.
sent_countrequirednumber—
failed_countrequirednumber—
pause_reasonrequiredobject | null—
created_atrequiredstring—
updated_atrequiredstring—
200401404409

Pause a campaign

POST/api/v1/email/campaigns/{id}/pause

POST /email/campaigns/{id}/pause
curl -X POST 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/pause' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "campaign",
  "id": "id_123",
  "name": "Example",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "topic_id": "topic_123",
  "from": "you@yourdomain.com",
  "subject": "Welcome to Acme",
  "preview_text": "string",
  "open_tracking": false,
  "click_tracking": false,
  "status": "draft",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "total_recipients": 1,
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "sent_count": 1,
  "failed_count": 1,
  "pause_reason": {
    "code": "user",
    "message": "string",
    "metric": "hard_bounce_rate",
    "value": 0,
    "threshold": 0,
    "sample": {
      "events": 0,
      "of": 0
    },
    "window": {
      "since": "string"
    },
    "decided_by": "floor",
    "resume": "self_serve",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Pause a scheduled or sending campaign. A paused send stops cleanly between recipients — already-sent messages are untouched, and no partial email is ever produced. Continue where it left off with Resume a campaign, or stop it for good with Cancel a campaign. Requires the campaigns:send capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
template_idrequiredstring—
segment_idrequiredstring—
topic_idrequiredstring | null—
fromrequiredstring—
subjectrequiredstring | null—
preview_textrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
scheduled_atrequiredstring | null—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
total_recipientsrequirednumberRecipients the engine admitted when the campaign started sending. 0 while it is `draft` or `scheduled`: read `projected_recipients`, or `sendable` from validate.
projected_recipientsobject | nullThe audience counted when the campaign was sent or scheduled: `total` segment members, `reachable` who will get it, `skipped` (unsubscribed, suppressed, excluded). Null for a draft that was never sent: read validate. Read-only.
sent_countrequirednumber—
failed_countrequirednumber—
pause_reasonrequiredobject | null—
created_atrequiredstring—
updated_atrequiredstring—
200401404409

Unschedule a campaign

POST/api/v1/email/campaigns/{id}/unschedule

POST /email/campaigns/{id}/unschedule
curl -X POST 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/unschedule' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "campaign",
  "id": "id_123",
  "name": "Example",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "topic_id": "topic_123",
  "from": "you@yourdomain.com",
  "subject": "Welcome to Acme",
  "preview_text": "string",
  "open_tracking": false,
  "click_tracking": false,
  "status": "draft",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "total_recipients": 1,
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "sent_count": 1,
  "failed_count": 1,
  "pause_reason": {
    "code": "user",
    "message": "string",
    "metric": "hard_bounce_rate",
    "value": 0,
    "threshold": 0,
    "sample": {
      "events": 0,
      "of": 0
    },
    "window": {
      "since": "string"
    },
    "decided_by": "floor",
    "resume": "self_serve",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Move a scheduled campaign (or one paused before it started sending) back to draft, same id, so you can edit it. Content, audience and overrides are kept; the saved send time is cleared, so the next Send a campaign needs an explicit scheduled_at (409 send_time_required without one). A campaign that started sending can't be unscheduled: cancel it and duplicate it (the copy goes to the whole segment again, including people the first run reached, unless you set excluded_contact_ids). No body; any key is a 422. Requires the campaigns:send capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
template_idrequiredstring—
segment_idrequiredstring—
topic_idrequiredstring | null—
fromrequiredstring—
subjectrequiredstring | null—
preview_textrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
scheduled_atrequiredstring | null—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
total_recipientsrequirednumberRecipients the engine admitted when the campaign started sending. 0 while it is `draft` or `scheduled`: read `projected_recipients`, or `sendable` from validate.
projected_recipientsobject | nullThe audience counted when the campaign was sent or scheduled: `total` segment members, `reachable` who will get it, `skipped` (unsubscribed, suppressed, excluded). Null for a draft that was never sent: read validate. Read-only.
sent_countrequirednumber—
failed_countrequirednumber—
pause_reasonrequiredobject | null—
created_atrequiredstring—
updated_atrequiredstring—
200401404409422

Results for several campaigns

GET/api/v1/email/campaigns/stats

GET /email/campaigns/stats
curl -X GET 'https://www.unitpost.com/api/v1/email/campaigns/stats' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "campaign_stats",
      "campaign_id": "campaign_123",
      "recipients": 0,
      "failed_recipients": 0,
      "suppressed": 0,
      "counts": {
        "sent": 0,
        "delivered": 0,
        "opened": 0,
        "clicked": 0,
        "unsubscribed": 0,
        "bounced": 0,
        "complained": 0,
        "failed": 0
      },
      "rates": {
        "delivery": 0,
        "open": 0,
        "click": 0,
        "unsubscribe": 0,
        "bounce": 0,
        "complaint": 0
      },
      "tracking": {
        "open": false,
        "click": false
      },
      "source": "live",
      "snapshotted_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

The same numbers as Campaign results for up to 100 campaigns in one read: ids, comma-separated. An id that isn't one of this workspace's email campaigns is left out of data, never an error. Pass ids once; a repeated or any other query key is a 422. Requires the campaigns:read capability.

Parameters1 field
FieldTypeDescription
idsrequiredstring · queryComma-separated campaign ids (1–100).
Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
campaign_idrequiredstring—
recipientsrequiredintegerContacts the campaign was sent to (suppressed addresses never became recipients).
failed_recipientsrequiredintegerRecipients that didn't receive it, including ones that failed before a message existed.
suppressedrequiredinteger | nullContacts left out at send because their address is suppressed; null for campaigns sent before this was counted.
countsrequiredobject—
ratesrequiredobjectPercentages with one decimal (12.3 = 12.3%). null when there is nothing to measure yet, or when that tracking was off.
trackingrequiredobject—
sourcerequiredenumlive | snapshot | combinedLive rows, the counts frozen when old messages were cleaned up, or both.
snapshotted_atrequiredstring | null—
200401403422503

Campaign results

GET/api/v1/email/campaigns/{id}/stats

GET /email/campaigns/{id}/stats
curl -X GET 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/stats' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "campaign_stats",
  "campaign_id": "campaign_123",
  "recipients": 0,
  "failed_recipients": 0,
  "suppressed": 0,
  "counts": {
    "sent": 0,
    "delivered": 0,
    "opened": 0,
    "clicked": 0,
    "unsubscribed": 0,
    "bounced": 0,
    "complained": 0,
    "failed": 0
  },
  "rates": {
    "delivery": 0,
    "open": 0,
    "click": 0,
    "unsubscribe": 0,
    "bounce": 0,
    "complaint": 0
  },
  "tracking": {
    "open": false,
    "click": false
  },
  "source": "live",
  "snapshotted_at": "2026-01-01T00:00:00.000Z"
}

A campaign's results: delivered, unique opens and clicks, unsubscribes, bounces, complaints and their rates, recipients, and who didn't receive it. Open and click rates are null when that tracking was off; every rate is null until something was sent. Old messages are cleaned up after your plan's retention window; their counts are kept (source). Requires the campaigns:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
campaign_idrequiredstring—
recipientsrequiredintegerContacts the campaign was sent to (suppressed addresses never became recipients).
failed_recipientsrequiredintegerRecipients that didn't receive it, including ones that failed before a message existed.
suppressedrequiredinteger | nullContacts left out at send because their address is suppressed; null for campaigns sent before this was counted.
countsrequiredobject—
ratesrequiredobjectPercentages with one decimal (12.3 = 12.3%). null when there is nothing to measure yet, or when that tracking was off.
trackingrequiredobject—
sourcerequiredenumlive | snapshot | combinedLive rows, the counts frozen when old messages were cleaned up, or both.
snapshotted_atrequiredstring | null—
200401403404422503

List who a campaign would reach

GET/api/v1/email/campaigns/{id}/recipients

GET /email/campaigns/{id}/recipients
curl -X GET 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/recipients' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "campaign_recipient",
      "contact_id": "contact_123",
      "email": "customer@example.com",
      "name": "Example",
      "status": "sendable",
      "reason": "string",
      "reason_code": "unsubscribed"
    }
  ],
  "next_cursor": "string"
}

Who the campaign would reach if sent now, one row per segment member, by the send's own rule: sendable, missing_data (a required variable has no value), suppressed or excluded, with the reason. The numbers of Validate a campaign, member by member. Rows run in contact-id order: pass next_cursor as after for the next page. A page can hold fewer rows than limit while has_more is true (a rare status in a big segment is walked in bounded steps). Rows name contacts, so this also requires contacts:read. Requires the campaigns:read capability.

Parameters4 fields
FieldTypeDescription
idrequiredstring · path—
statusstring · queryOnly members with this outcome (default `all`).
limitinteger · queryRows per page (1–100, default 50).
afterstring · queryThe previous page's `next_cursor`.
Response · 200 fields7 fields
FieldTypeDescription
objectrequiredstring—
contact_idrequiredstring—
emailrequiredstring | null—
namerequiredstring | null—
statusrequiredenumsendable | missing_data | suppressed | excludedWhat a send now would do for this member, by the send's own rule.
reasonrequiredstring | nullWhy, in plain words; null when sendable.
reason_coderequiredenum | null—
200401403404409422503

List addresses a quality pause flagged

GET/api/v1/email/campaigns/{id}/quality/affected

GET /email/campaigns/{id}/quality/affected
curl -X GET 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/quality/affected' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "campaign_affected_recipient",
      "email": "customer@example.com",
      "contact_id": "contact_123",
      "reason": "hard_bounce"
    }
  ]
}

After an automatic quality pause: the recipients whose message hard-bounced (hard_bounce) or drew a spam complaint (complaint). They're already suppressed; this is for cleaning the source list. By address, limit per page (default and most 10,000); when has_more, pass the last row's email as after for the rest. Take them out of the campaign's segment with Remove flagged addresses. Requires the campaigns:read capability.

Parameters3 fields
FieldTypeDescription
idrequiredstring · path—
limitinteger · queryAddresses per page, 1–10,000 (default 10,000).
afterstring · queryThe last row's `email` from the previous page.
Response · 200 fields4 fields
FieldTypeDescription
objectrequiredstring—
emailrequiredstring—
contact_idrequiredstring | null—
reasonrequiredenumhard_bounce | complaintThe address doesn't exist (`hard_bounce`), or the person marked it as spam.
200401403404422503

Remove flagged addresses from the audience

POST/api/v1/email/campaigns/{id}/quality/remove-affected

POST /email/campaigns/{id}/quality/remove-affected
curl -X POST 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/quality/remove-affected' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "campaign_quality_removal",
  "removed": 0
}

While a campaign is paused for its delivery quality: take every hard-bounced and complained contact out of its static segment. It edits a reusable segment for good. Each removal records its activity and fires segment.left (the first at once, the rest within a few minutes); a repeat removes nothing. A campaign that isn't paused for quality, or a filter (dynamic) segment, is a 409 (a filter's matches can't be removed one by one, and they're suppressed anyway). It doesn't resume the campaign. No body. Requires the segments:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields2 fields
FieldTypeDescription
objectrequiredenumcampaign_quality_removal—
removedrequiredinteger—
200400401403404409422503

Request a review for a paused campaign

POST/api/v1/email/campaigns/{id}/quality/request-review

POST /email/campaigns/{id}/quality/request-review
curl -X POST 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/quality/request-review' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "campaign_review_request",
  "requested": false,
  "already_requested": false
}

When a campaign the delivery-quality check paused again needs our team's review before it can resume (Resume a campaign answers 409 review_required): ask for that review. Our team is notified once a day per campaign; a repeat answers already_requested: true and notifies no one. A campaign that isn't waiting for a review is a 409, and so is one paused while our team reviews the whole account (resume: account_review). No body. Requires the campaigns:send capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields3 fields
FieldTypeDescription
objectrequiredenumcampaign_review_request—
requestedrequiredboolean—
already_requestedrequiredboolean—
200400401403404409422

Duplicate a campaign

POST/api/v1/email/campaigns/{id}/duplicate

POST /email/campaigns/{id}/duplicate
curl -X POST 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/duplicate' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 201
{
  "object": "campaign",
  "id": "id_123",
  "name": "Example",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "topic_id": "topic_123",
  "from": "you@yourdomain.com",
  "subject": "Welcome to Acme",
  "preview_text": "string",
  "open_tracking": false,
  "click_tracking": false,
  "status": "draft",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "total_recipients": 1,
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "sent_count": 1,
  "failed_count": 1,
  "pause_reason": {
    "code": "user",
    "message": "string",
    "metric": "hard_bounce_rate",
    "value": 0,
    "threshold": 0,
    "sample": {
      "events": 0,
      "of": 0
    },
    "window": {
      "since": "string"
    },
    "decided_by": "floor",
    "resume": "self_serve",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Copy a campaign into a new draft. Only configuration is copied (name, template, segment, sender, subject, preview text, topic, tracking overrides, fallbacks, exclusions), never the send time or status, and every create check runs again (template published, segment not archived, domain, limits). Optional name for the copy; any other key is a 422. Pass an Idempotency-Key so a retry returns the same copy instead of making another. Requires the campaigns:write capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
Idempotency-Keystring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Request body1 field
FieldTypeDescription
namestringName of the copy. Defaults to the source's name with " (copy)".
Response · 201 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
template_idrequiredstring—
segment_idrequiredstring—
topic_idrequiredstring | null—
fromrequiredstring—
subjectrequiredstring | null—
preview_textrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
scheduled_atrequiredstring | null—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
total_recipientsrequirednumberRecipients the engine admitted when the campaign started sending. 0 while it is `draft` or `scheduled`: read `projected_recipients`, or `sendable` from validate.
projected_recipientsobject | nullThe audience counted when the campaign was sent or scheduled: `total` segment members, `reachable` who will get it, `skipped` (unsubscribed, suppressed, excluded). Null for a draft that was never sent: read validate. Read-only.
sent_countrequirednumber—
failed_countrequirednumber—
pause_reasonrequiredobject | null—
created_atrequiredstring—
updated_atrequiredstring—
201400401403404409422

Resume a campaign

POST/api/v1/email/campaigns/{id}/resume

POST /email/campaigns/{id}/resume
curl -X POST 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/resume' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "campaign",
  "id": "id_123",
  "name": "Example",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "topic_id": "topic_123",
  "from": "you@yourdomain.com",
  "subject": "Welcome to Acme",
  "preview_text": "string",
  "open_tracking": false,
  "click_tracking": false,
  "status": "draft",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "total_recipients": 1,
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "sent_count": 1,
  "failed_count": 1,
  "pause_reason": {
    "code": "user",
    "message": "string",
    "metric": "hard_bounce_rate",
    "value": 0,
    "threshold": 0,
    "sample": {
      "events": 0,
      "of": 0
    },
    "window": {
      "since": "string"
    },
    "decided_by": "floor",
    "resume": "self_serve",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Resume a paused campaign. Sending continues with the recipients that hadn't been reached yet — only them: contacts who joined the segment after the campaign started are not added, and anyone already delivered to is skipped, so nobody receives the campaign twice. After an automatic quality pause (pause_reason.code hard_bounce_rate, complaint_rate or quality_review) the quality check measures only sends made after the resume. A campaign whose scheduled_at is still in the future waits for it; otherwise it sends immediately. Resume runs the same checks as Send a campaign and answers with the same errors; the campaign stays paused when one fails. Pause a send with Pause a campaign. Requires the campaigns:send capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
template_idrequiredstring—
segment_idrequiredstring—
topic_idrequiredstring | null—
fromrequiredstring—
subjectrequiredstring | null—
preview_textrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
scheduled_atrequiredstring | null—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
total_recipientsrequirednumberRecipients the engine admitted when the campaign started sending. 0 while it is `draft` or `scheduled`: read `projected_recipients`, or `sendable` from validate.
projected_recipientsobject | nullThe audience counted when the campaign was sent or scheduled: `total` segment members, `reachable` who will get it, `skipped` (unsubscribed, suppressed, excluded). Null for a draft that was never sent: read validate. Read-only.
sent_countrequirednumber—
failed_countrequirednumber—
pause_reasonrequiredobject | null—
created_atrequiredstring—
updated_atrequiredstring—
200401402403404409429

Reschedule a campaign

POST/api/v1/email/campaigns/{id}/reschedule

POST /email/campaigns/{id}/reschedule
curl -X POST 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/reschedule' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "scheduled_at": "2026-07-01T15:00:00Z"
  }'
Response · 200
{
  "object": "campaign",
  "id": "id_123",
  "name": "Example",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "topic_id": "topic_123",
  "from": "you@yourdomain.com",
  "subject": "Welcome to Acme",
  "preview_text": "string",
  "open_tracking": false,
  "click_tracking": false,
  "status": "draft",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "total_recipients": 1,
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "sent_count": 1,
  "failed_count": 1,
  "pause_reason": {
    "code": "user",
    "message": "string",
    "metric": "hard_bounce_rate",
    "value": 0,
    "threshold": 0,
    "sample": {
      "events": 0,
      "of": 0
    },
    "window": {
      "since": "string"
    },
    "decided_by": "floor",
    "resume": "self_serve",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Move a scheduled campaign to a new send time: scheduled_at in ISO 8601 with Z or an offset, in the future and inside your plan's scheduling window; the response returns it in UTC (a time without a timezone is still read as UTC, deprecated). A draft is scheduled with Send a campaign instead. Only campaigns that haven't started sending can be rescheduled — once a send is in flight, pause or cancel it instead. Requires the campaigns:send capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body1 field
FieldTypeDescription
scheduled_atrequiredstringISO 8601 with `Z` or a `±hh:mm` offset; returned in UTC. A time without a timezone is read as UTC (deprecated: include the zone).
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
template_idrequiredstring—
segment_idrequiredstring—
topic_idrequiredstring | null—
fromrequiredstring—
subjectrequiredstring | null—
preview_textrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
scheduled_atrequiredstring | null—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
total_recipientsrequirednumberRecipients the engine admitted when the campaign started sending. 0 while it is `draft` or `scheduled`: read `projected_recipients`, or `sendable` from validate.
projected_recipientsobject | nullThe audience counted when the campaign was sent or scheduled: `total` segment members, `reachable` who will get it, `skipped` (unsubscribed, suppressed, excluded). Null for a draft that was never sent: read validate. Read-only.
sent_countrequirednumber—
failed_countrequirednumber—
pause_reasonrequiredobject | null—
created_atrequiredstring—
updated_atrequiredstring—
200401404409422502

Validate a campaign

GET/api/v1/email/campaigns/{id}/validate

GET /email/campaigns/{id}/validate
curl -X GET 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/validate' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "campaign_validation",
  "total_members": 1,
  "sendable": 0,
  "suppressed": 0,
  "excluded": 0,
  "missing_data": [
    {
      "contact_id": "contact_123",
      "email": "customer@example.com",
      "missing": [
        "string"
      ]
    }
  ],
  "unresolved_variables": [
    "string"
  ],
  "variable_coverage": [
    {
      "name": "Example",
      "missing_count": 1,
      "eligible": 0,
      "missing_for_all": false,
      "has_default": false
    }
  ],
  "blockers": [
    {
      "code": "string",
      "message": "string"
    }
  ],
  "can_send": false,
  "warnings": [
    {
      "code": "QUOTA_OVERSUBSCRIBED",
      "severity": "info",
      "title": "string",
      "message": "string",
      "guide_url": "https://example.com",
      "fix_url": "https://example.com"
    }
  ]
}

Run a non-mutating pre-send check and get the full readiness report: how many contacts will receive the campaign (sendable), how many are suppressed or excluded, which contacts are missing template variables, variable_coverage[] per variable (missing_for_all: a variable_fallbacks default is required to send; otherwise a default is optional and only fills the blanks), blockers, warnings, and a final can_send verdict. Nothing is sent or changed. Show the user sendable, the blockers and the warnings before sending. Fix reported variable gaps with Update a campaign (variable_fallbacks / excluded_contact_ids), then launch with Send a campaign. Requires the campaigns:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields11 fields
FieldTypeDescription
objectrequiredenumcampaign_validation—
total_membersrequiredinteger—
sendablerequiredinteger—
suppressedrequiredinteger—
excludedrequiredinteger—
missing_datarequiredobject[]—
unresolved_variablesrequiredstring[]—
variable_coverageobject[]Per template variable that some recipients lack, missing-for-all first. `missing_for_all`: no recipient has it, so a `variable_fallbacks` default is REQUIRED to send. Otherwise a default is optional and only fills the `missing_count` blanks (it never replaces a recipient's own value); or exclude those contacts. `has_default`: the campaign already sets one.
blockersobject[]What refuses Send right now (draft template, archived segment, unverified domain, …). The same codes as a blocked send's `error.details[].code`.
can_sendrequiredboolean—
warningsrequiredobject[]Deliverability warnings: advice that never blocks `can_send` (credits that may run short, a saved send time that has passed so Send sends now, no subscription topic; and, once switched on, a young sending domain, a send far above your usual volume, no DMARC, recipients mailed in the last few days). Most severe first, at most three. Show them to whoever is about to send.
200202401404

Search docs and guides

Search the docs and product guides.