Campaigns

Campaigns let you send one email to an entire audience. You can schedule campaigns in advance or send immediately.

Campaign lifecycle

draft → scheduled → sending → sent
                 └→ cancelled

---

Create campaign

POST /v1/campaigns

Requires full_access scope.

Request body

{
  "name": "March Newsletter",
  "subject": "What's new in March",
  "from": "Newsletter <news@acme.com>",
  "audience_id": "aud_abc123",
  "html": "<h1>March Update</h1><p>Here's what happened this month...</p>",
  "unsubscribe_url": "https://acme.com/unsubscribe",
  "scheduled_at": "2025-03-15T09:00:00Z"
}

Field	Type	Required	Description
name	string	Yes	Campaign name (internal).
subject	string	Yes	Email subject line.
from	string	Yes	Sender address. Domain must be verified.
audience_id	string	Yes	ID of the audience to send to.
html	string	No*	HTML body. At least one of html or text required.
text	string	No*	Plain-text body.
template_id	string	No	Use a saved template.
unsubscribe_url	string	Yes	Unsubscribe URL for CAN-SPAM compliance.
scheduled_at	string	No	ISO 8601 datetime. Omit to send immediately.

Response

{
  "id": "camp_abc123",
  "name": "March Newsletter",
  "status": "scheduled",
  "audience_id": "aud_abc123",
  "subject": "What's new in March",
  "scheduled_at": "2025-03-15T09:00:00Z",
  "created_at": "2025-03-12T09:00:00Z"
}

---

Get campaign

GET /v1/campaigns/:id

Requires read_only scope.

---

List campaigns

GET /v1/campaigns

Requires read_only scope.

---

Update campaign

PATCH /v1/campaigns/:id

Requires full_access scope. Only campaigns in draft or scheduled status can be updated.

---

Cancel campaign

POST /v1/campaigns/:id/cancel

Requires full_access scope. Cancels a scheduled campaign before it starts sending. Cannot cancel a campaign that is already in sending or sent status.

---

Delete campaign

DELETE /v1/campaigns/:id

Requires full_access scope. Only draft or cancelled campaigns can be deleted.

---

Campaign stats

GET /v1/campaigns/:id/stats

Requires read_only scope. Returns delivery statistics for a sent campaign.

{
  "campaign_id": "camp_abc123",
  "total": 4200,
  "sent": 4198,
  "delivered": 4100,
  "opened": 1722,
  "clicked": 492,
  "bounced": 98,
  "complained": 4,
  "unsubscribed": 12
}

---

Plan limits

Plan	Campaigns
Free	3
Pro	25
Business	Unlimited
Enterprise	Unlimited

Marketing emails sent via campaigns count toward the marketingEmailsPerMonth quota. Free plan does not allow marketing emails (quota = 0).