Batch send

Send the same template to many recipients in a single API call, with per-recipient merge variables.

Ideal for digests, receipts and notifications.

POST /v3/messages.batch

The batch endpoint accepts up to 5,000 recipients per call. Each recipient renders independently and produces its own message.id — failures on one recipient never block the others.

Body parameters

Recipient object

Each entry in recipients describes one rendered message. Per-recipient vars are merged on top of global_vars, so you can keep shared content in one place and only pass what differs.

Responses

Asynchronous batches

Every batch is accepted asynchronously — there is no header to send and nothing to change on the client. The request itself validates the batch (structure, sender domain, sandbox rules, every recipient address), reserves its sending quota and assigns every message_id; the messages are then persisted by a background worker in paced chunks instead of on the request thread, so a campaign of many large batches never holds API connections or the database while your transactional traffic is served.

The 201 body is unchanged: the same { batch_id, accepted, rejected, message_ids, rejected_recipients? } with every per-recipient message_id. A Location header points at the batch status resource, GET /v3/batches/{batch_id}, which reports progress.

{
  "batch_id": "batch_7f3a2b1c9d8e4f50",
  "accepted": 840,
  "rejected": 0,
  "message_ids": ["msg_…", "msg_…"]
}

• Errors stay synchronous. Structural validation (400), sandbox/allow-list (403), an unknown template (404), quota or rate limits (402/429) and a paused account (503) are answered on the request itself — a 201 means the batch is accepted, its quota reserved and every message_id assigned.
• Optionally poll the batch. You already have every message_id in the 201, but you can also follow the Location header — GET /v3/batches/{batch_id} moves accepted → processing → completed (or partial / failed) and lists each message_id with its recipient and delivery status. See Get batch status. GET /v3/messages/{id} answers for every accepted id right away (as queued), even before the worker has written the row.
• Same semantics as before. Recipient validation, rejected_recipients accounting, suppression checks, partial-fill, idempotency (Idempotency-Key replays the same 201, batch_id and headers) and per-message webhooks behave exactly as they did when batches were persisted on the request — only *where* the rows are written changed.
• `Prefer: respond-async` is a no-op. The RFC 7240 header that used to opt a batch into this mode is still accepted for compatibility and echoed as Preference-Applied: respond-async; it changes nothing else. Keep sending it or drop it — both are fine.
• Back-pressure. If the platform is momentarily saturated, any request may receive 503 with error code service_busy and a Retry-After header — wait the indicated seconds and retry; nothing was accepted.

What is a tag?

A tag is a short label you attach to a sent message — think hashtag, not category. Tags are how you slice your sending data later: every event, dashboard chart, suppression filter, and webhook payload carries the tags of the originating message, so you can ask questions like "what's the bounce rate of password-reset emails this week?" without scanning the body or subject.

Code examples

curl -X POST https://api.wemail.io/v3/messages.batch \
  -H "Authorization: Bearer afn_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <noreply@updates.acme.io>",
    "subject": "Hi {{first_name}}, your {{month}} statement is ready",
    "html": "<p>Hi {{first_name}}, your balance is {{balance}}.</p>",
    "global_vars": { "month": "May", "portal_url": "https://acme.io/billing" },
    "tags": ["statement", "may-2026"],
    "headers": { "X-TES-MSGID": "tes-batch-may26" },
    "recipients": [
      { "to": "alex@example.com", "vars": { "first_name": "Alex", "balance": "$42.10" } },
      { "to": "ben@example.com", "vars": { "first_name": "Ben", "balance": "$11.00" } }
    ]
  }'

await wemail.messages.batch({
  from: "Acme <noreply@updates.acme.io>",
  subject: "Hi {{first_name}}, your {{month}} statement is ready",
  html: "<p>Hi {{first_name}}, your balance is {{balance}}.</p>",
  global_vars: { month: "May", portal_url: "https://acme.io/billing" },
  tags: ["statement", "may-2026"],
  // applied to every message in the batch; echoed on each message's webhooks
  headers: { "X-TES-MSGID": "tes-batch-may26" },
  recipients: users.map(u => ({
    to: u.email,
    name: u.fullName,
    vars: { first_name: u.firstName, balance: u.balance },
    tags: [`plan:${u.plan}`, `locale:${u.locale}`],
    metadata: { user_id: u.id, variant: u.experimentVariant },
  })),
});

wemail.messages.batch(
    from_="Acme <noreply@updates.acme.io>",
    subject="Hi {{first_name}}, your {{month}} statement is ready",
    html="<p>Hi {{first_name}}, your balance is {{balance}}.</p>",
    global_vars={"month": "May", "portal_url": "https://acme.io/billing"},
    tags=["statement", "may-2026"],
    recipients=[
      { "to": u.email, "vars": {"first_name": u.first_name, "balance": u.balance} }
      for u in users
    ],
)

$wemail->messages->batch([
  'from' => 'noreply@updates.acme.io',
  'subject' => 'Hi {{first_name}}',
  'html' => '<p>Your balance is {{balance}}</p>',
  'recipients' => $recipients,
]);

wemail.messages.batch(
  from: "noreply@updates.acme.io",
  subject: "Hi {{first_name}}",
  html: "<p>Your balance is {{balance}}</p>",
  recipients: recipients
)

_, err := client.Messages.Batch(ctx, &wemail.BatchParams{
  From: "noreply@updates.acme.io",
  Subject: "Hi {{first_name}}",
  HTML: "<p>Your balance is {{balance}}</p>",
  Recipients: recipients,
})

wemail.messages().batch(BatchParams.builder()
  .from("noreply@updates.acme.io")
  .subject("Hi {{first_name}}")
  .html("<p>Your balance is {{balance}}</p>")
  .recipients(recipients).build());

await wemail.Messages.BatchAsync(new BatchParams {
  From = "noreply@updates.acme.io",
  Subject = "Hi {{first_name}}",
  Html = "<p>Your balance is {{balance}}</p>",
  Recipients = recipients,
});

{
  "batch_id": "batch_01HBZK22N4DQ",
  "accepted": 2,
  "rejected": 0,
  "message_ids": [
    "msg_01HBZK22NB3Q…",
    "msg_01HBZK22NB4R…"
  ]
}