Bulk Send

The Bulk Send API lets you queue a marketing campaign — subject, body, and a recipient list of up to 50,000 addresses — in one request. All bulk jobs are treated as marketing emails: unsubscribed recipients are skipped automatically and List-Unsubscribe headers are injected. The system delivers in the background at a controlled rate, handling suppression, quota deduction, and DKIM signing automatically.

You can also create and track campaigns from the Bulk Send page in the dashboard.

Create a bulk job

POST/v1/user/email/bulk

Field	Type	Required	Notes
`fromEmail`	`string`	Yes	Must use a verified sender domain
`fromName`	`string`	No	Defaults to account business name → first name → email local part
`subject`	`string`	Yes	Max 998 characters
`bodyHtml`	`string`	No*	Required if bodyText is omitted. Omit to use your configured email template.
`bodyText`	`string`	No*	Required if bodyHtml is omitted
`recipients`	`string[]`	Yes	Array of email strings, 1–50,000. Duplicates are deduplicated.

Response 202: { jobId, totalCount, status: "pending" }

Check job status

GET/v1/user/email/bulk/:jobId

{
  "jobId": "uuid",
  "status": "pending | processing | completed | paused_quota",
  "totalCount": 4000,
  "sentCount": 1800,
  "suppressedCount": 42,
  "failedCount": 3,
  "remainingCount": 2155,
  "createdAt": "...",
  "startedAt": "...",
  "completedAt": null
}

List recent jobs

GET/v1/user/email/bulk

Returns the 20 most recent jobs for the authenticated account, sorted newest first.

Job status values

Status	Meaning
`pending`	Job created, waiting for the worker to start
`processing`	Worker is actively sending recipients
`completed`	All recipients processed
`paused_quota`	Quota exhausted mid-job — resumes automatically after billing is topped up

iBulk jobs honour the same suppression rules as single sends: hard-bounced addresses are always skipped; marketing emails skip recipients who have unsubscribed. Quota is deducted per delivered (non-suppressed) recipient. See Suppressions & Unsubscribes to list your suppressed addresses or let a user re-subscribe.

Bulk send checks quota per-recipient, not atomically

Unlike a single send with CC/BCC (which checks its whole recipient count in one atomic operation), a bulk job's worker checks quota one recipient at a time. If your monthly quota and PAYG credits run out partway through a job, recipients already processed stay sent — the job pauses at paused_quota instead of failing outright, and resumes automatically once more quota becomes available. See Quota & Billing for the single-send comparison.