Create a campaign
POST/api/v1/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"
}'{
"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
| Field | Type | Description |
|---|---|---|
namerequired | string | — |
template_idrequired | string | — |
segment_id | string | — |
recipients | string[] | — |
topic_id | string | — |
fromrequired | string | — |
subject | string | — |
preview_text | string | — |
scheduled_at | string | ISO 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_tracking | boolean | null | — |
click_tracking | boolean | null | — |
variable_fallbacks | object | — |
excluded_contact_ids | string[] | — |
Response · 201 fields22 fields
| Field | Type | Description |
|---|---|---|
objectrequired | string | — |
idrequired | string | — |
namerequired | string | — |
template_idrequired | string | — |
segment_idrequired | string | — |
topic_idrequired | string | null | — |
fromrequired | string | — |
subjectrequired | string | null | — |
preview_textrequired | string | null | — |
open_trackingrequired | boolean | null | — |
click_trackingrequired | boolean | null | — |
statusrequired | enumdraft | scheduled | sending | paused | sent | canceled | failed | — |
scheduled_atrequired | string | null | — |
variable_fallbacksrequired | object | — |
excluded_contact_idsrequired | string[] | — |
total_recipientsrequired | number | Recipients the engine admitted when the campaign started sending. 0 while it is `draft` or `scheduled`: read `projected_recipients`, or `sendable` from validate. |
projected_recipients | object | null | The 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_countrequired | number | — |
failed_countrequired | number | — |
pause_reasonrequired | object | null | — |
created_atrequired | string | — |
updated_atrequired | string | — |