Sign inGet Started

Create a batch of email messages

POST
/v1/email/batches
const batch = await bird.email.sendBatch({
  messages: [
    {
      from: { email: "onboarding@messagebird.dev", name: "Bird" },
      to: ["alice@example.com"],
      subject: "Your receipt",
      html: "<p>Thanks, Alice.</p>",
    },
    {
      from: { email: "onboarding@messagebird.dev", name: "Bird" },
      to: ["bob@example.com"],
      subject: "Your receipt",
      html: "<p>Thanks, Bob.</p>",
    },
  ],
});
for (const item of batch.data) console.log(item.id, item.status);
Réponse202
{
  "data": [
    {
      "id": "em_01krdgeqcxet5s7t44vh8rt9mg",
      "status": "accepted",
      "category": "marketing",
      "requested_language": "pt-BR",
      "resolved_language": "pt-BR",
      "template_id": "emt_01krdgeqcxet5s7t44vh8rt9mg",
      "template_version_id": "emv_01krdgeqcxet5s7t44vh8rt9mg"
    },
    {
      "id": "em_01krdgeqcxet5s7t44vh8rt9mh",
      "status": "accepted",
      "category": "transactional",
      "scheduled_at": "2026-05-22T09:00:00Z"
    }
  ]
}

Accepts up to 100 independent email messages and queues them for delivery. All items are validated before any are queued: if one fails validation, the entire batch is rejected. Field-level validation failures and business-rule failures, such as sending from a domain that is not verified, both return 422. An item can set scheduled_at to send it later, on the same terms as a single scheduled send, and one batch can mix scheduled and immediate messages. Cancel a scheduled item before it sends with Cancel an email message. Suppression is evaluated per recipient after acceptance, never as a synchronous error. The 202 response returns one entry per message in submission order, each with its own id you can use to fetch that message or match it against webhook events. Attachments are allowed per message. Each message must stay within the 20 MB estimated generated message-size cap, and the serialized JSON request body for the whole batch has a hard 20 MB cap.

Corps de la requête

messages
array of object
obligatoire

Email message send requests, up to 100. All items are validated before any are queued. Attachments are allowed on individual messages. Each message must stay within the 20 MB estimated generated message-size cap. The serialized JSON request body for the batch has a hard 20 MB cap.

Afficher les paramètres enfants

Contenu de la réponse

data
array of object
obligatoire

One entry per message in the batch, in submission order.

Afficher les attributs enfants
data.id
string
obligatoire

Message ID assigned to this batch item.

data.status
string
obligatoire

Initial status of this message in the batch.

Possible values: accepted

data.category
string
obligatoire

Resolved category for this batch item.

Possible values: marketing, transactional

data.requested_language
nullable string

The template language this item asked for, in canonical form. Null when the item named no language or used no template. Every item in a batch resolves its own template reference, so this and resolved_language can differ from item to item.

data.resolved_language
nullable string

The template language this item was actually delivered in, in canonical form. Null when the item used no template. A value here differing from requested_language means the template did not have the language asked for and its on_missing_language policy chose this one.

data.template_id
nullable string

The template this item rendered from, or null for an item that supplied its content inline.

data.template_version_id
nullable string

The exact template version this item rendered from, or null for an inline item. Record it if you need to reproduce what was sent: a template's live version changes every time you submit it.

data.scheduled_at
string

When this item is scheduled to send, for an item created with a future send time. Absent for an item that sends immediately.

Poursuivez avec la documentation, les guides et les exemples sur ce sujet.