Campaigns

Newsletter campaigns, audience filters, fan-out, and lifecycle states.

Campaigns send a template to a filtered slice of your audience. At send time, MailingCore fans out one queued email per matching contact (respecting locale routing, suppressions, and monthly quota).

Required API key scopes: campaigns:read (list and read) and campaigns:write (create, test, schedule, send, cancel).

Authorization: Bearer mc_live_xxxx
X-Tenant-Id: clxxxxxxxx

Create a campaign

POST /campaigns

{
  "name": "June product update",
  "templateVersionId": "clxversion...",
  "subject": "What's new in June",
  "audienceFilter": {
    "locale": "en",
    "optIn": true,
    "projectId": "clxproject...",
    "attributes": { "plan": "pro" }
  },
  "timezone": "Europe/Madrid"
}

Field	Required	Description
`name`	Yes	Internal campaign name (max 200)
`templateVersionId`	No	Published template version to send
`subject`	No	Override subject (max 998)
`audienceFilter`	No	Who receives the campaign
`projectId`	No	SMTP project
`timezone`	No	IANA timezone for scheduling

Audience filter

Field	Description
`locale`	Only contacts with this locale
`optIn`	Typically `true` for marketing
`projectId`	Project-scoped audience
`attributes`	Match custom JSON attributes

Lifecycle states

Status	Meaning
`DRAFT`	Created; not scheduled or sent
`SCHEDULED`	Waiting for `scheduledAt`
`SENDING`	Fan-out in progress
`SENT`	Delivery complete
`CANCELLED`	Stopped before or during send

List and filter:

GET /campaigns?status=DRAFT&page=1&limit=20

Management endpoints

Action	Endpoint
Get one	`GET /campaigns/{id}`
Update draft	`PATCH /campaigns/{id}`
Test send	`POST /campaigns/{id}/test`
Schedule	`POST /campaigns/{id}/schedule`
Send now	`POST /campaigns/{id}/send`
Cancel	`POST /campaigns/{id}/cancel`
Locale coverage	`GET /campaigns/{id}/locale-coverage`

Full step-by-step flow: Campaign workflow.

Templates and locale

Campaigns use a published template version. For multi-language audiences, create locale variants of the same template and rely on contact locale for routing — or run separate campaigns per language.

Check readiness with Locale coverage before scheduling.