Batch sending

POST /emails/batch takes an array of up to 100 emails and queues them in a single request. Each email uses the same fields as POST /emails, with two exceptions: batch emails cannot have attachments or scheduled_at.

curl -X POST https://api.usend.et/emails/batch \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "from": "Acme <[email protected]>",
      "to": ["[email protected]"],
      "subject": "Your receipt",
      "html": "<p>Thanks, Ann!</p>"
    },
    {
      "from": "Acme <[email protected]>",
      "to": ["[email protected]"],
      "subject": "Your receipt",
      "html": "<p>Thanks, Ben!</p>"
    }
  ]'

import { Usend } from '@usend/node';

const usend = new Usend(process.env.USEND_API_KEY);

const { data, error } = await usend.batch.send([
  {
    from: 'Acme <[email protected]>',
    to: ['[email protected]'],
    subject: 'Your receipt',
    html: '<p>Thanks, Ann!</p>',
  },
  {
    from: 'Acme <[email protected]>',
    to: ['[email protected]'],
    subject: 'Your receipt',
    html: '<p>Thanks, Ben!</p>',
  },
]);

result = usend.batch.send([
    {
        "from": "Acme <[email protected]>",
        "to": ["[email protected]"],
        "subject": "Your receipt",
        "html": "<p>Thanks, Ann!</p>",
    },
    {
        "from": "Acme <[email protected]>",
        "to": ["[email protected]"],
        "subject": "Your receipt",
        "html": "<p>Thanks, Ben!</p>",
    },
])

The response lists the new IDs in the same order as the request:

{
  "data": [
    { "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c" },
    { "id": "9a2c5f10-7b1e-4d0f-8a6b-2f4c1e9d3b77" }
  ]
}

Each email in a batch counts as one email toward your quota. The batch is one API request for rate limiting.

#Validation modes

The x-batch-validation header decides what happens when some emails are invalid.

#Strict (default)

Without the header, or with x-batch-validation: strict, the batch is all-or-nothing. If any email is invalid, nothing is sent and the request fails with the error of the first invalid email. Validation messages are prefixed with the email's position in the array, for example Email 3: The subject field is required.

#Permissive

With x-batch-validation: permissive, valid emails are sent and invalid ones are reported in an errors array. index is the zero-based position of the email in your request.

curl -X POST https://api.usend.et/emails/batch \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -H "x-batch-validation: permissive" \
  -d '[
    { "from": "Acme <[email protected]>", "to": ["[email protected]"], "subject": "Hi", "text": "Hi Ann" },
    { "from": "Acme <[email protected]>", "to": ["not-an-address"], "subject": "Hi", "text": "Hi" }
  ]'

{
  "data": [
    { "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c" }
  ],
  "errors": [
    { "index": 1, "message": "Invalid `to` field: ..." }
  ]
}

With the SDKs, pass the mode as an option: usend.batch.send(emails, { validation: 'permissive' }) in Node.js, or usend.batch.send(emails, validation="permissive") in Python.

In permissive mode errors is always present, and is an empty array when every email was valid. In both modes, organization-level checks such as sandbox rules and quotas apply to the whole batch: if they fail, nothing is sent.

#Idempotency

Send an Idempotency-Key header to make retries safe. Repeating a batch request with the same key within 24 hours returns the first response instead of sending again. See Idempotency.