Send a batch of emails

POSThttps://api.mailfully.com/v1/emails/batch

Accept a JSON array of 1–100 email objects, each identical to the single send body. The batch is all-or-nothing: every object is validated and prepared before any write, so the first invalid object aborts the whole batch with a single 422 whose param names the offending index (for example [37].to), and a quota/spend/daily-cap denial rejects the entire batch. A refused batch saves nothing, queues nothing, and uses no daily allowance. On success returns 202 with one accepted id per input object, in request order. Requires the send scope. Honors the optional Idempotency-Key header.

Loading code example

Loading code example

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Header Parameters

Idempotency-Keystring

Opt-in idempotency key, 1–256 characters (no charset restriction). A repeated key with the same body within 24 hours replays the original 2xx response verbatim; the same key with a different body returns 409.

Length: >= 1, <= 256

Body

Response

application/json

All emails in the batch were accepted.

dataarray<object>required

One accepted email per input object, in request order.

data.object"email"required

Allowed values: "email"

data.idstringrequired

The accepted message id (a bare ULID, no prefix).

data.status"queued" | "canceled"required

queued normally. canceled when every recipient was suppressed, in which case nothing was queued and nothing will be sent.

Allowed values: "queued" | "canceled"

data.type"transactional" | "marketing"required

The kind of mail, as the sender declares it. Omitting the field means transactional. A marketing send is subject to extra compliance rules — it accepts exactly one recipient across to/cc/bcc, the organization must have a postal address on file, and it draws on a separate monthly marketing allowance.

Allowed values: "transactional" | "marketing"

Default: "transactional"

data.toarray<string>required

data.ccarray<string>required

data.bccarray<string>required

data.fromstringrequired

data.subjectstringrequired

data.scheduled_atstring<date-time>required

data.created_atstring<date-time>required