Campaigns API
Campaigns are one-time or recurring broadcast emails sent to a targeted audience (segment). They support scheduling, A/B testing, and detailed per-recipient analytics.
Note
For a platform guide on campaigns, see Campaigns. Campaigns require JWT authentication (dashboard).
Authentication
All campaign endpoints require JWT authentication (dashboard session). API key access is not available for campaigns.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /v1/campaigns | List campaigns |
POST | /v1/campaigns | Create a campaign |
GET | /v1/campaigns/{id} | Get campaign details |
PATCH | /v1/campaigns/{id} | Update a campaign (draft only) |
DELETE | /v1/campaigns/{id} | Delete a campaign (draft only) |
POST | /v1/campaigns/{id}/schedule | Schedule a campaign |
POST | /v1/campaigns/{id}/send | Send a campaign immediately |
POST | /v1/campaigns/{id}/cancel | Cancel a scheduled/sending campaign |
POST | /v1/campaigns/{id}/pause | Pause a sending campaign |
POST | /v1/campaigns/{id}/resume | Resume a paused campaign |
POST | /v1/campaigns/{id}/duplicate | Duplicate a campaign |
POST | /v1/campaigns/{id}/test-send | Send a test email |
POST | /v1/campaigns/{id}/audience-preview | Preview the target audience |
GET | /v1/campaigns/{id}/analytics | Get campaign analytics |
GET | /v1/campaigns/{id}/recipients | List recipients and their status |
GET | /v1/campaigns/{id}/best-send-time | Get recommended send time |
A/B Testing
| Method | Path | Description |
|---|---|---|
GET | /v1/campaigns/{id}/ab-results | Get A/B test results |
POST | /v1/campaigns/{id}/ab-send-winner | Send the winning variant to the remaining audience |
Recurring Campaigns
| Method | Path | Description |
|---|---|---|
POST | /v1/campaigns/{id}/schedule-recurring | Start a recurring campaign |
POST | /v1/campaigns/{id}/stop-recurring | Stop a recurring campaign |
POST | /v1/campaigns/{id}/resume-recurring | Resume a stopped recurring campaign |
GET | /v1/campaigns/{id}/instances | List send instances |
GET | /v1/campaigns/{id}/instances/{instance_id} | Get instance details |
Campaign Lifecycle
draft -> scheduled -> sending -> sent
| | |
| v v
| cancelled paused -> resumed -> sent
| |
| cancelled
v
deleted
A/B Testing Lifecycle
draft -> ab_testing -> (auto-evaluate after test period) -> sent (winner to remaining)
Recurring Lifecycle
draft -> recurring -> (instances on schedule) -> stopped -> resumed
|
cancelled
Create Campaign
POST /v1/campaigns
Request Body
json
{
"name": "May Newsletter",
"subject": "What's new in May",
"template_id": "t1a2b3c4-5678-90ab-cdef-1234567890ab",
"segment_id": "s1a2b3c4-5678-90ab-cdef-1234567890ab",
"sender_name": "Acme Team",
"sender_email": "[email protected]",
"reply_to": "[email protected]"
}
Analytics
GET /v1/campaigns/{id}/analytics
Returns delivery metrics: sent, delivered, opened, clicked, bounced, spam reports, and calculated rates (open rate, click rate, bounce rate).
Test Send
POST /v1/campaigns/{id}/test-send
Send a preview email to up to 5 test recipients before launching the campaign.
json