Batch Validation Modes

Use batch validation modes to control how emails are validated in batch sending.

PPedro Gomes

We recently enabled a new feature to help you control how emails are validated in batch sending.

Choose between two modes:

  • Strict mode (default): sends the batch only if all emails in the request are valid.
  • Permissive mode: processes all emails, allowing for partial success and returning validation errors if present.

Traditionally, the Resend API enforced a strict validation mode, failing the batch if any email in your payload was invalid (e.g., required fields are missing, fields contain invalid data, etc.).

The new permissive mode, however, allows for more flexibility. Now, sending a batch of emails with an invalid payload for some emails, will not fail the entire batch. Instead, valid emails will be queued and invalid emails will be returned in the errors array.

How does it work?

Set the batch validation header to permissive to enable the new permissive mode (otherwise strict mode automatically applies).

import { Resend } from 'resend';


const resend = new Resend('re_xxxxxxxxx');


const { data, errors } = await resend.batch.send(
  [
    {
      from: 'Acme <onboarding@resend.dev>',
      to: ['foo@gmail.com'],
      subject: 'hello world',
      html: '<h1>it works!</h1>',
    },
    {
      from: 'Acme <onboarding@resend.dev>',
      to: ['bar@outlook.com'],
      subject: 'world hello',
      html: '<p>it works!</p>',
    },
  ],
  {
    batchValidation: 'permissive',
  },
);

Example response

With strict mode enabled, the batch will only be sent if all emails are valid. A successful response will return the ids of the queued emails:

{
  "data": [
    {
      "id": "ae2014de-c168-4c61-8267-70d2662a1ce1"
    },
    {
      "id": "faccb7a5-8a28-4e9a-ac64-8da1cc3bc1cb"
    }
  ]
}

With permissive mode enabled, the batch will be sent even if some emails are invalid. The data array returns all valid emails and the errors array includes the invalid emails and the reason they couldn't be created.

{
  "data": [
    {
      "id": "ae2014de-c168-4c61-8267-70d2662a1ce1"
    },
    {
      "id": "faccb7a5-8a28-4e9a-ac64-8da1cc3bc1cb"
    }
  ],
  "errors": [
    {
      "index": 2, // 0-indexed (first item is index 0)
      "message": "The `to` field is missing."
    }
  ]
}

Note that the index references the email index in the payload of your request.

Understanding errors

If an email is invalid, it means Resend was unable to create it in our system.

Reasons your email may cause an error include:

  • Required fields are missing.
  • Fields contain invalid data.
  • The batch contains more than 100 emails.

Importantly, this means the following:

  • The email will not appear in the dashboard, since it could not be created.
  • The error object will be included in the errors array.
  • The only way to understand why the email failed is to inspect the returned error object.

For more details, see our Batch Validation Mode documentation. We hope this additional flexibility empowers you to send emails with more confidence and recovery from failures more gracefully.

And as always, our team of email experts is here to help you troubleshoot any issues you may encounter.