Batch Email Operations

Relevant source files

The following files were used as context for generating this wiki page:

• src/batch/batch.ts
• src/batch/batch.spec.ts
• src/common/utils/parse-email-to-api-options.ts
• src/common/utils/parse-email-to-api-options.spec.ts
• src/resend.ts
• src/emails/emails.ts

Batch Email Operations allow you to send multiple emails in a single API request. This system processes a list of email objects, handles React component rendering, and submits the collection to the /emails/batch endpoint.

Sources: src/batch/batch.ts:1-42, src/batch/batch.spec.ts:101-135

Core Architecture

The Batch class provides methods to group and dispatch email requests. It interacts with the Resend base class to perform HTTP POST operations. Each email in the batch can be a standard HTML/Text email or a template-based email.

The diagram shows the data flow from the client request through rendering and parsing to the final API call.
Sources: src/batch/batch.ts:16-41, src/common/utils/parse-email-to-api-options.spec.ts:1-120

Key Methods

The Batch module exposes two primary methods for sending emails in bulk.

Method	Description
send(payload, options)	Alias for the create method. It accepts a list of email options and optional request configurations.
create(payload, options)	Processes the email list and submits the batch to the Resend API.

Sources: src/batch/batch.ts:16-24

Request Processing Logic

When you call the batch creation methods, the system performs the following steps:

1. Iterates through the payload array.
2. If an email contains a react property, the system renders the component into an HTML string and clears the React element.
3. Converts camelCase properties (like replyTo and scheduledAt) to snake_case (like reply_to and scheduled_at) using the utility parser.
4. Appends custom headers and validation settings.
5. Executes a POST request to the /emails/batch endpoint.

Sources: src/batch/batch.ts:25-41, src/common/utils/parse-email-to-api-options.spec.ts:22-38

Configuration Options

Batch operations support specific request options to control API behavior, such as validation strictness and idempotency.

Option	Type	Default	Description
batchValidation	'strict' | 'permissive'	'strict'	Controls how the API handles individual email failures within the batch.
idempotencyKey	string	undefined	Prevents duplicate processing of the same batch request.
headers	HeadersInit	undefined	Custom HTTP headers to include in the request.

Sources: src/batch/batch.ts:34-39, src/batch/batch.spec.ts:175-197

Data Structures

Batch Payload

The payload is an array of email objects. Each object can include standard fields or template-specific fields.

// Example of a mixed batch payload structure
const payload = [
  {
    from: 'onboarding@resend.com',
    to: 'user@example.com',
    subject: 'Welcome',
    html: '<h1>Hello!</h1>'
  },
  {
    to: 'customer@example.com',
    template: {
      id: 'template_id_123',
      variables: { name: 'John' }
    }
  }
];

Sources: src/batch/batch.spec.ts:219-250, src/common/utils/parse-email-to-api-options.spec.ts:40-100

API Response

The response from the batch operation returns an object containing an array of email IDs or an error object if the request fails.

The class diagram represents the structure of the data returned by the batch endpoint, including handling for permissive validation modes.
Sources: src/batch/batch.spec.ts:114-135, src/batch/batch.spec.ts:199-217

Validation Modes

The x-batch-validation header determines how the Resend API responds to partial failures.

1. Strict Mode (Default): The entire request fails if any single email in the batch is invalid.
2. Permissive Mode: The API processes valid emails and returns a 202 status code. The response includes an errors field indicating which indices failed.

Sources: src/batch/batch.ts:34-35, src/batch/batch.spec.ts:199-231

Conclusion

Batch Email Operations provide a performant way to scale email delivery by reducing the number of round-trips to the API. By supporting React rendering and flexible validation modes, the system allows for complex bulk mailing workflows while maintaining reliability through features like idempotency keys.