Campaigns

A campaign ties together a template, an audience query, a send schedule, and throttling settings into a single send job. PostMTA handles audience deduplication, suppression filtering, per-recipient personalisation, and delivery throttling automatically.

Create a Campaign

POST to /v1/campaigns to create and immediately enqueue a campaign. The response includes the campaign ID and initial state.

{create_campaign}

Request fields

Field	Type	Required	Description
`name`	string	Yes	Internal name for the campaign.
`description`	string	No	Human-readable description.
`template_id`	string	Yes	ID of the template to use.
`from`	object	Yes	Envelope sender address and optional display name.
`subject`	string	Yes	Override the template subject. Supports Handlebars.
`template_vars`	object	No	Global template variables merged into every recipient's vars.
`audience_query`	string	Yes	SQL SELECT returning `email` (and optionally per-recipient vars).
`schedule`	object	Yes	`type: "now"` or `type: "scheduled"` + `send_at`.
`throttle`	object	No	Max messages per second and per hour.
`track_opens`	boolean	No	Enable open tracking. Default `true`.
`track_clicks`	boolean	No	Enable click tracking. Default `true`.
`suppression_list_id`	string	No	Apply a named suppression list before sending.

Audience Segmentation

The audience_query is a SQL SELECT run against your uploaded contact table or an external data connection. The query must return at least an email column. Additional columns become per-recipient template_vars.

Example: select contacts with specific tags:

{segment_tags}

PostMTA executes the query at send time. The results are held in memory during the send window. Any runtime query error cancels the campaign with status failed.

Deduplication: If the same email address appears multiple times in the query result, only the first occurrence is sent. Duplicate emails are counted in the queued total but do not generate additional sends.

Schedule: Send Now vs Scheduled

Send Now

{send_now}

The campaign enters a queued state immediately and begins sending as soon as throttling rules permit.

Scheduled Send

Set schedule.type to scheduled and provide an ISO 8601 UTC timestamp in send_at. Scheduled campaigns can be cancelled or modified up to 1 minute before the scheduled time.

"schedule": {
  "type":    "scheduled",
  "send_at": "2026-07-25T09:00:00Z"
}

Throttling

Throttling controls how fast messages are released from the campaign queue. Limits are enforced globally across all campaigns and cannot exceed your plan limits.

{throttle_settings}

Field	Default	Max	Description
`max_per_second`	50	500	Maximum messages injected per second across all campaigns.
`max_per_hour`	100,000	Plan limit	Maximum messages injected per rolling hour.

Burst handling: PostMTA allows short bursts up to 2x max_per_second for up to 5 seconds to account for warm-up and TCP behaviour. Sustained rates above the limit are capped.

Campaign Analytics

Retrieve aggregate statistics for a campaign:

{campaign_analytics}

Example response:

{suppression_response}

Rate Definitions

Metric	Formula
Delivery rate	`delivered / sent`
Bounce rate	`bounced / sent`
Open rate	`opens_unique / delivered` (requires `track_opens: true`)
Click rate	`clicks_unique / delivered` (requires `track_clicks: true`)
Complaint rate	`complained / delivered`

Suppression Integration

Every campaign automatically applies the workspace-level suppression list. You can additionally specify a named suppression_list_id to layer campaign-specific suppressions on top.

Recipients who appear in any applicable suppression list are silently skipped at send time. They do not appear in bounce or complaint counts.

Pause and Resume

While a campaign is sending, you can pause it. Pausing halts new message injection immediately but does not cancel messages already in the queue or in transit.

{campaign_pause}

Resume a paused campaign:

{campaign_resume}

Resume restarts injection from where it left off, respecting throttling limits.

Cancel a Campaign

Cancelling stops injection and marks all remaining queued messages as cancelled. Already-sent messages are not recalled. Cancelled campaigns cannot be resumed.

{campaign_cancel}

Campaign status transitions: queued → sending → completed | paused → resumed → completed | cancelled | failed.

Campaign Tags and Filtering

Tag campaigns with arbitrary string labels at creation time using the tags field. Tags are useful for filtering campaigns in analytics dashboards and for correlating delivery performance across related send jobs:

"tags": ["summer-2026", "promotional", "us-east"]

Tags do not affect delivery behaviour. Use them to segment analytics views in the PostMTA dashboard under App → Analytics → Campaigns.