Resources

Email campaigns API

Create, list, update and delete campaigns, send immediately, or schedule a send for a future time.

How campaigns work

A campaign is a one-time email sent to an audience: a newsletter, a product launch, a sale announcement. Each campaign has a sender, a subject line, email content and an audience - either everyone (recipient_type: "all"), one list ("list") or a segment ("segment"). Only subscribers with status active receive the send; suppressed and unsubscribed contacts are excluded automatically.

A campaign moves through a simple lifecycle: it is created as a draft, can be scheduled for a future time, becomes sending when the send starts, and ends as sent (or failed if the send could not start). Drafts and scheduled campaigns can be edited and deleted; sent campaigns are immutable so your statistics always match what was actually sent.

Use cases

Generate a recurring digest from your own data, create the campaign via API and send it automatically.
Build campaigns in your own tooling or CMS and hand them to the platform for delivery.
Schedule sends at the optimal local time per audience, computed by your own logic.
Poll campaign status and recipient counts to display send progress in an internal dashboard.

The campaign object

Name	Type	Description
`id`	string	Unique campaign id.
`name`	string	Internal name, not shown to recipients.
`sender_name / sender_email`	string	The from name and address. The email must be on a domain you have verified.
`subject_line / preheader_text`	string	Subject and inbox preview text. Merge tags such as {{firstName}} are supported.
`email_content`	object	The email body, for example { "html": "..." }.
`status`	string	draft, scheduled, sending, sent or failed.
`recipient_type / recipient_id`	string	The audience: all, or list/segment plus the matching id.
`scheduled_at`	string	UTC timestamp for scheduled sends.
`sent_count / open_rate / click_rate`	number	Delivery and engagement statistics, populated after sending.

Sending is irreversible

The send endpoint starts delivery immediately and cannot be cancelled once processing begins. Send and schedule calls are limited to 5 per minute. Test with a small list first, and prefer schedule over send when you need a safety window.

Endpoints

GET

Get campaigns

/campaigns-api

Query parameters

Name	Type	Description
`status`	string	Filter by status (draft, scheduled, sent, failed).
`search`	string	Search by name or subject line.
`limit`	number	Items per page (default: 50).
`offset`	number	Pagination offset.

curl -X GET "https://api.mailingplatform.net/campaigns-api?status=draft&limit=25" \
  -H "Authorization: Bearer mp_live_..."

GET

Get single campaign

/campaigns-api/{campaignId}

Retrieve one campaign by id.

Query parameters

Name	Type	Description
`campaignId`required	string	Campaign id (path).
`include_stats`	boolean	When true, adds recipient_count based on the audience (all, list or segment).

curl -X GET "https://api.mailingplatform.net/campaigns-api/{campaignId}?include_stats=true" \
  -H "Authorization: Bearer mp_live_..."

POST

Create campaign

/campaigns-api

Create a new campaign. It starts as a draft unless you pass another status; send it with the send endpoint below.

Request body

Name	Type	Description
`name`required	string	Internal campaign name.
`sender_name`required	string	From name recipients see.
`sender_email`required	string	From address on your verified domain.
`subject_line`required	string	Subject line.
`preheader_text`	string	Inbox preview text.
`email_content`	object	Email content, for example { "html": "..." }.
`recipient_type`	string	all, list or segment (default: all).
`recipient_id`	string	List or segment id when recipient_type is list or segment. Required for those types, and must belong to your account - otherwise the request fails with 404 "List not found" or "Segment not found".
`status`	string	Initial status (default: draft).
`scheduled_at`	string	UTC timestamp for a scheduled send.

curl -X POST "https://api.mailingplatform.net/campaigns-api" \
  -H "Authorization: Bearer mp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Weekly Newsletter",
  "sender_name": "Your Company",
  "sender_email": "news@company.com",
  "subject_line": "This Week's Updates",
  "preheader_text": "The short preview text",
  "recipient_type": "list",
  "recipient_id": "list-456",
  "status": "draft"
}'

PUT

Update campaign

/campaigns-api/{campaignId}

Update a draft or scheduled campaign. All fields are optional; only the fields you send are changed. Sent campaigns cannot be edited. If you change recipient_type or recipient_id, the resulting list or segment must belong to your account (404 otherwise).

Name	Type	Description
`campaignId`required	string	Campaign id (path).

curl -X PUT "https://api.mailingplatform.net/campaigns-api/{campaignId}" \
  -H "Authorization: Bearer mp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "subject_line": "Updated subject line",
  "recipient_type": "segment",
  "recipient_id": "segment-789"
}'

DELETE

Delete campaign

/campaigns-api/{campaignId}

Delete a campaign. Campaigns that are sending or already sent cannot be deleted.

Name	Type	Description
`campaignId`required	string	Campaign id (path).

curl -X DELETE "https://api.mailingplatform.net/campaigns-api/{campaignId}" \
  -H "Authorization: Bearer mp_live_..."

POST

Send campaign

/campaigns-api/{campaignId}/send

Sends the campaign immediately to all recipients. Campaign must be in 'draft' or 'scheduled' status.

Name	Type	Description
`campaignId`required	string	Campaign id (path).

curl -X POST "https://api.mailingplatform.net/campaigns-api/{campaignId}/send" \
  -H "Authorization: Bearer mp_live_..."

POST

Schedule campaign

/campaigns-api/{campaignId}/schedule

Request body

Name	Type	Description
`scheduled_at`required	string	UTC timestamp, for example 2024-12-25T10:00:00Z.

curl -X POST "https://api.mailingplatform.net/campaigns-api/{campaignId}/schedule" \
  -H "Authorization: Bearer mp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "scheduled_at": "2024-12-25T10:00:00Z"
}'