Sending Campaigns | Cakemail Documentation

A campaign goes through a lifecycle: create → configure content → test → schedule → send. Here's how to do each step via the API.

Create a campaign

curl -X POST https://api.cakemail.dev/campaigns \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "April Newsletter"}'

The response includes a campaign_id and a status of draft.

Configure the campaign

Update the campaign with sender, audience, and content:

curl -X PATCH https://api.cakemail.dev/campaigns/{campaign_id} \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": {"sender_id": 123},
    "audience": {"list_id": 456},
    "content": {
      "subject": "Our April Newsletter",
      "html": "<html><body><h1>Hello!</h1><p>Welcome to our newsletter.</p></body></html>"
    }
  }'

You need a confirmed sender. See the API reference for all available fields.

Preview the campaign

Render the campaign to see what it will look like:

curl "https://api.cakemail.dev/campaigns/{campaign_id}/render" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Send a test email

Before sending to your full audience, send a test:

curl -X POST https://api.cakemail.dev/campaigns/{campaign_id}/send-test \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"test_email": "you@example.com"}'

Schedule the campaign

curl -X POST https://api.cakemail.dev/campaigns/{campaign_id}/schedule \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scheduled_for": "2026-04-15T10:00:00Z"}'

Omit scheduled_for to send immediately.

Campaign lifecycle

Status	Meaning
`draft`	Campaign is being built. Can be edited.
`scheduled`	Campaign is scheduled for sending.
`delivering`	Campaign is being sent.
`delivered`	Campaign has been fully sent.

Only draft campaigns can be edited or deleted.

List campaigns

Retrieve your campaigns with pagination and optional status filtering:

curl "https://api.cakemail.dev/campaigns?page=1&per_page=50&status=delivered" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Parameter	Description
`page`	Page number (default: 1)
`per_page`	Results per page (default: 50)
`status`	Filter by status: `draft`, `scheduled`, or `delivered`

Campaign reports

Get delivery statistics for a campaign:

curl "https://api.cakemail.dev/reports/campaigns/{campaign_id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

The response includes aggregate counts: sent, opened, clicked, bounced, and unsubscribed.

Campaign logs

Get per-recipient activity for a campaign:

curl "https://api.cakemail.dev/logs/campaigns/{campaign_id}?page=1&per_page=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Results are paginated. Use page and per_page to navigate through the activity log.

Using MCP

With the Execution MCP, your AI assistant can manage the full campaign lifecycle:

campaigns tool with operation list — view your campaigns
campaigns tool with operation create — start a new campaign
campaigns tool with operation schedule — schedule for delivery