POST/emails/send-bulk

POST /emails/send-bulk

Send bulk email to a list or a set of contacts.

Request

curl -X POST 'https://api.sendheron.com/api/v1/emails/send-bulk' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json'

Required scopes

The key must carry these:

emails:send

Body parameters

Name	Type	Required	Description
templateId	uuid	Yes	Template to render.
listId	uuid	No	Send to every contact in a list. Lists are dashboard-only for now, so the id has to come from there.
contactIds	uuid[]	No	Send to these contacts.
sendToAll	boolean	No	Send to every subscribed contact in this workspace.
from	string	No	Sender address. Defaults to the workspace's default sender identity; with none configured, the send is suppressed with `SENDER_NOT_CONFIGURED`.
sampleData	object	No	Template variables rendered into every recipient's send, not only a preview. Each recipient's own `contact.*` values are set on top.

Bulk sends are ALWAYS marketing, even when the template is tagged TRANSACTIONAL. They get the unsubscribe link, they respect opt-outs, and they are measured on the marketing stream. A channel can only ever make a message more strictly regulated, never less, because the alternative would make TRANSACTIONAL a switch for stripping unsubscribe links off a mass mailing. Bulk sends are permission-based only: see the anti-spam policy before using this endpoint. A product launch announcement and a product update are typical bulk sends. The response is { batchId, totalRecipients, queued, blocked }: queued counts recipients that will be attempted, blocked counts compliance refusals (suppressed or unsubscribed addresses) rather than failures, and batchId is a UUID naming this launch, null when nothing queued. A queued recipient can still wait for daily sending capacity, new-sender warm-up or the checks on an old imported list: its send record reads queued with a holdReason until it goes out by itself. Re-sending the same template to the same audience is fully supported; every launch is its own batch. One more property worth knowing before you automate against this: the template is read and rendered per recipient at processing time, not snapshotted at launch, so editing a template while its launch is still queued changes what the unprocessed recipients receive. Give each variant its own template instead of patching one template between launches.

Responses

Returns 201 on success.

400: The payload failed validation, or the request is not valid for the current state. The body's description names the field and says what was wrong with it in words, e.g. "domain: domain must be a bare hostname such as acme.com, with no scheme, path, or port". The error code is stable and safe to branch on; description is for the human reading the log.
401: Missing or invalid API key.
403: Valid key, but it does not carry the required scope. The error code is apiKeys.insufficientScopes and the description names both halves of the problem: "Missing required scope(s): X. This key holds: Y." Neither is a secret, since the required scopes are on this page and the held ones are your own credential, and a bare "Forbidden" costs a debugging pass to work out which of the two it was.
404: No such record in this workspace. An id belonging to a different workspace returns this too, never a 403, because the API will not confirm that a record exists outside the workspace your key was issued in. Read it as "not yours or not there" rather than as "definitely gone".
409: A duplicate, or an idempotency key reused with a different payload.
429: Either rate-limit ceiling was exceeded.
403: subscription.sendPoolExhausted: the pooled monthly send allowance is spent, so the launch is refused whole rather than sending a partial audience. One pool gates every marketing route the same way: dashboard campaigns, this endpoint, direct sends of marketing templates, and sequence sends. Bulk is always marketing, so the 10% transactional grace never applies here. The pool resets with the calendar month; a higher tier raises it.
403: subscription.lapsed: no active subscription. Marketing sending is refused entirely while lapsed.

Rate limits

10/min per key (tighter than the default), counted against the organization's SEND ceiling (200/min). Both windows are one minute. They limit requests; how much mail goes out in a day is under Daily sending.