API reference

Campaigns

List, manage, send, and report on email campaigns. Paths are relative to https://app.blacklistguard.com/api/v1 and require your X-API-Key header.

List campaigns

GET /campaigns

Query parameters: page, limit. Returns a campaigns array plus a pagination object. Each campaign carries its own counts and rates — sent_count, open_rate, bounce_count, mailing_list_name, and so on.

Get a campaign

GET /campaigns/{id}

Returns the full campaign, including its content, delivery settings, and current stats.

Create & update

POST /campaigns
PUT  /campaigns/{id}

Both take the campaign object as the JSON body. PUT is a full-object update. A new campaign is created as a draft; start delivery with POST /campaigns/{id}/send.

Core fields

Field	Type	Required	Notes
`name`	string	Yes	Internal campaign name.
`subject`	string	Yes	Subject line.
`from_email`	string	Yes	Must be on a verified domain or a verified sender, else `400`.
`from_name`	string	No	Sender display name.
`reply_to`	string	No	Reply-to address.
`message_type`	string	No	`email` (default) or `sms`.
`phone_field_name`	string	SMS only	Subscriber field holding the phone number.

Targeting

Field	Type	Notes
`recipient_type`	string	`mailing_list`, `segment`, or `custom`. Auto-detected if omitted (`segment_id` → segment, else `segment_conditions` → custom, else mailing list).
`mailing_list_id`	uuid	A single list (multiple lists aren't supported). Validated when you send, not on create.
`segment_id`	uuid	Used when `recipient_type` is `segment`.
`segment_conditions`	JSON	Inline segment rules (see segment operators). Required when `recipient_type` is `custom`.

Content

Field	Type	Notes
`html_content`	string	HTML body.
`text_content`	string	Plain-text body.

Tracking & delivery

Field	Type	Notes
`enable_open_tracking`	bool	Omit to inherit the list's default.
`enable_click_tracking`	bool	Omit to inherit the list's default.
`url_domain_id`	uuid	Tracking domain for links.
`use_custom_headers`	bool	Enable the raw header block below.
`custom_headers`	string	Raw headers, used when `use_custom_headers` is true.
`virtual_mta_ip`	string	A sending IP, or `routing_rule:<uuid>` to select a routing rule.
`routing_rule_id`	uuid	Routing rule to send through.
`bounce_email`	string	Where bounces are routed.
`sender_email`	string	Envelope sender override.

Scheduling & attachments

Field	Type	Notes
`scheduled_at`	datetime	Interpreted in your workspace's timezone, stored as UTC. Dispatch still happens via the scheduler or `/send`.
`attachments`	array	Same shape as Send an email: `{ filename, content_type, content, disposition, content_id }`.

ℹNot supported: A/B testing, preheader/preview text, and multiple lists per campaign (use one mailing_list_id, or a segment / custom conditions).

The response is the created or updated campaign — read back its id, status (draft on create), recipient_type, total_recipients, timestamps, and the stat fields (sent_count, open_count, rates — all zero until it sends). status, sent_at, and the statistics are system-managed and read-only.

⚠Only draft campaigns can be edited. Once a campaign is scheduled, sending, sent, paused, or cancelled, PUT returns 409 with code CONFLICT — duplicate it into a new draft to make changes.

Send, pause & resume

POST /campaigns/{id}/send
POST /campaigns/{id}/pause
POST /campaigns/{id}/resume

send begins delivery to the campaign's audience. pause halts an in-progress send; resume continues it.

Delete

DELETE /campaigns/{id}

Analytics

GET /campaigns/{id}/activity
GET /campaigns/{id}/smtp-domain-stats
GET /campaigns/{id}/messages
GET /campaigns/{id}/recent-activity

activity — hourly cumulative series: [{ time, sent, opens, clicks, unsubscribes, complaints }].
smtp-domain-stats — delivery broken down by recipient domain: { pagination, stats:[{ domain, total_messages, percent_total, success, bounced, failure, still_trying }] }.
messages — per-recipient results: { messages:[{ id, time, localpart, domain, status, attempts, error_message }], pagination }. Filter with status, email, page, limit.
recent-activity — per-event feed: { activities:[{ id, type, email, description, timestamp }], pagination } where type is sent|opened|clicked|bounced|unsubscribed|complained.