Campaigns
Single broadcast sends delivered to an audience you choose
A campaign is a single broadcast to an audience you define — think newsletters, product launches, announcements, or promotions. Where a workflow keeps running over time, a campaign fires exactly once (right away or at a scheduled moment) and is immutable afterwards.
Anatomy of a campaign
Everything required to render and deliver one batch of emails lives on the campaign itself:
Prop
Type
After sending, the campaign stores denormalised counters — totalRecipients, sentCount, deliveredCount, openedCount, clickedCount, bouncedCount — retrievable through GET /campaigns/:id/stats.
Targeting an audience
There are three ways to define who a campaign reaches:
ALL— all subscribed contacts in the project; the fastest route to a full-list broadcast.SEGMENT— the current members of one of your segments, so existing targeting logic can be reused.FILTERED— an inline condition written directly on the campaign (same JSON structure as segment filters). Ideal when you want a bespoke audience for a single send and don't need a saved segment.
Campaigns of type MARKETING or HEADLESS automatically leave out anyone who has unsubscribed. A TRANSACTIONAL campaign, by contrast, reaches every matching contact whether subscribed or not — reserve it for content that is genuinely transactional, and use it rarely.
Sender domain verification
Bitelio only accepts a from address whose domain has been verified for sending; otherwise creating or updating the campaign fails with 403. See Verifying domains.
Lifecycle
| Status | Meaning |
|---|---|
DRAFT | Exists but hasn't been scheduled or sent yet; still editable. |
SCHEDULED | Queued for a future scheduledFor time; can still be cancelled. |
SENDING | Delivery underway — recipients are being worked through the queue. |
SENT | Delivery finished; the stats won't change anymore. |
CANCELLED | Stopped before finishing. A terminal state reachable from DRAFT, SCHEDULED, or SENDING. |
A campaign in SENT or CANCELLED can neither be edited nor sent again. To iterate on it, call POST /campaigns/:id/duplicate and work on the resulting copy.
Sending and scheduling
POST /campaigns/:id/send kicks off delivery. Sending runs asynchronously in the background — small lists finish within seconds, while very large audiences take longer. The campaign detail page in the dashboard shows live progress.
A SCHEDULED or SENDING campaign can be stopped with POST /campaigns/:id/cancel. Note that cancelling only prevents future sends; any email already accepted by a recipient's mail server is beyond recall.
Test sends
POST /campaigns/:id/test delivers a single preview email. The body takes one address — { email: "you@example.com" } — not a list. Variables resolve exactly as they would in the real send, but delivery goes to the address you supplied, which makes test sends a convenient way to check personalisation using your own contact record.
Duplicating
Calling POST /campaigns/:id/duplicate produces a fresh DRAFT that copies the original's content, audience, and settings. Handy for A/B variants or campaigns you send on a recurring basis.
API reference
The complete list of campaign endpoints — list, get, create, update, delete, send, cancel, duplicate, test, and stats — lives in the API overview.