Campaigns

One-time broadcast sends to a list or segment, rendered from a template.

Create a campaign

Exactly one of `list_id` or `segment_id` is required — a campaign sends to a static list or a live segment, never both.

POST

/campaigns

Authorizations

Authorization

string

header

required

API key for your workspace, scoped to campaigns:manage. Pass it as a Bearer token in the Authorization header.

Body · application/json

name

string

subject

string

template_id

number

sender_id

number

list_id

number

Create a campaign

curl https://api.mailcraft.host/v1/campaigns \
  -X POST \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "September newsletter",
    "subject": "What'\''s new this month",
    "template_id": 9,
    "sender_id": 3,
    "list_id": 4
  }'

{
  "data": {
    "id": 5,
    "name": "September newsletter",
    "subject": "What's new this month",
    "template_id": 9,
    "sender_id": 3,
    "list_id": 4,
    "segment_id": null,
    "status": "draft",
    "scheduled_at": null,
    "started_at": null,
    "completed_at": null,
    "stats": null,
    "created_at": "2026-09-22T14:20:00.000000Z"
  }
}

List campaigns

GET

/campaigns

Authorizations

Authorization

string

header

required

API key for your workspace, scoped to campaigns:manage. Pass it as a Bearer token in the Authorization header.

List campaigns

curl https://api.mailcraft.host/v1/campaigns \
  -H 'Authorization: Bearer sk_live_...'

{
  "data": [
    { "id": 5, "name": "September newsletter", "status": "draft" }
  ]
}

Get a campaign

GET

/campaigns/{campaign}

Authorizations

Authorization

string

header

required

API key for your workspace, scoped to campaigns:manage. Pass it as a Bearer token in the Authorization header.

Get a campaign

curl https://api.mailcraft.host/v1/campaigns/5 \
  -H 'Authorization: Bearer sk_live_...'

{
  "data": {
    "id": 5,
    "name": "September newsletter",
    "status": "sent",
    "stats": { "sent": 812, "delivered": 799, "opened": 401, "clicked": 88 },
    "started_at": "2026-09-22T14:25:00.000000Z",
    "completed_at": "2026-09-22T14:31:00.000000Z"
  }
}

Send a campaign

Transitions the campaign from `draft`/`scheduled` to `sending`, materializes the recipient list, and dispatches through the rate-limited send queue.

POST

/campaigns/{campaign}/send

Authorizations

Authorization

string

header

required

API key for your workspace, scoped to campaigns:manage. Pass it as a Bearer token in the Authorization header.

Send a campaign

curl https://api.mailcraft.host/v1/campaigns/5/send \
  -X POST \
  -H 'Authorization: Bearer sk_live_...'

{
  "data": { "id": 5, "status": "sending", "started_at": "2026-09-22T14:25:00.000000Z" }
}

Delete a campaign

DELETE

/campaigns/{campaign}

Authorizations

Authorization

string

header

required

API key for your workspace, scoped to campaigns:manage. Pass it as a Bearer token in the Authorization header.

Delete a campaign

curl https://api.mailcraft.host/v1/campaigns/5 \
  -X DELETE \
  -H 'Authorization: Bearer sk_live_...'

(empty body)