Batch Emails API

Relevant source files

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

• src/batch.rs
• src/emails.rs
• src/lib.rs
• src/idempotent.rs
• CHANGELOG.md

The Batch Emails API allows you to trigger up to 100 email transmissions in a single API call. This service reduces the number of HTTP requests required when sending messages to multiple recipients simultaneously.

The API resides within the BatchSvc struct and interacts with the /emails/batch endpoint. It supports two validation modes, strict and permissive, to control how the system handles individual email failures within a batch.

Sources: src/batch.rs:18-24, src/batch.rs:51-53

Architecture and Data Flow

The batch system wraps multiple CreateEmailBaseOptions objects into a single request. The BatchSvc utilizes an Arc<Config> to build and send asynchronous or synchronous requests depending on the enabled crate features.

Request Flow

When you call a batch send method, the client performs the following steps:

1. Converts the input into an Idempotent<T> wrapper.
2. Builds a POST request to the /emails/batch endpoint.
3. Attaches the x-batch-validation header based on the selected BatchValidation mode.
4. Includes the Idempotency-Key header if one is provided.
5. Serializes the collection of emails into the JSON request body.

Validation Modes

The API provides the BatchValidation enum to define how the server processes batch requests.

Mode	Description	Behavioral Outcome
Strict	The default mode. Sends the batch only if every email is valid.	Atomic: one failure rejects the entire batch.
Permissive	Processes all emails in the batch independently.	Partial Success: returns valid IDs and an error array.

Sources: src/batch.rs:72-88

Data Structures

Batch Request and Response Types

The API uses specific structures to handle batch results and permissive error reporting.

pub struct SendEmailBatchPermissiveResponse {
    /// The IDs of the sent emails.
    pub data: Vec<CreateEmailResponse>,
    /// Array of objects for emails which could not be created due to validation errors.
    #[serde(default)]
    pub errors: Vec<PermissiveBatchErrors>,
}

pub struct PermissiveBatchErrors {
    /// Index of the email in the batch request
    pub index: i32,
    /// Error message identifying the validation error
    pub message: String,
}

Sources: src/batch.rs:105-119

Core Components Table

Component	Type	File Path	Description
BatchSvc	Struct	src/batch.rs	Main service for batch operations.
CreateEmailBaseOptions	Struct	src/emails.rs	Individual email configuration including from, to, subject, and body.
Idempotent<T>	Struct	src/idempotent.rs	Wrapper for attaching idempotency keys to batch requests.
CreateEmailResponse	Struct	src/emails.rs	Contains the unique EmailId for a successful transmission.

Sources: src/batch.rs:14-16, src/emails.rs:133-162, src/lib.rs:219-222

Idempotency

Batch emails support a single idempotency key for the entire batch. Using the same key for a batch request ensures that the operation is performed only once, even if the request is retried.

Condition: You must provide the key via with_idempotency_key or by wrapping the iterator in the Idempotent struct.

Implementation Details

The BatchSvc implementation provides two primary methods for sending emails.

send

This method uses Strict validation by default. It returns a simple Vec<CreateEmailResponse> on success or an Error if any email fails.
Sources: src/batch.rs:25-37

send_with_batch_validation

This method allows explicit selection of the BatchValidation mode. It returns a SendEmailBatchPermissiveResponse, which contains both successful IDs and a list of specific errors indexed to the original request array.
Sources: src/batch.rs:40-66

Summary

The Batch Emails API provides a high-throughput interface for sending up to 100 emails per call to the Resend service. By utilizing the BatchSvc, developers can choose between atomic (Strict) or partial (Permissive) delivery strategies while maintaining safety through unified idempotency keys. This module is essential for applications handling bulk notifications, newsletters, or automated multi-recipient sequences.