Sending Batch Emails
Relevant source files
The following files were used as context for generating this wiki page:
- src/main/java/com/resend/services/batch/Batch.java
- src/main/java/com/resend/services/batch/model/CreateBatchEmailsResponse.java
- src/main/java/com/resend/services/batch/model/AbstractBatchEmailsResponse.java
- src/main/java/com/resend/services/emails/model/CreateEmailOptions.java
- src/test/java/com/resend/services/batch/BatchTest.java
- src/main/java/com/resend/core/net/impl/HttpClient.java
The Batch module sends multiple emails in a single API request to improve efficiency when processing high volumes of messages. It supports sending up to 100 emails simultaneously.
Sources: [src/main/java/com/resend/services/batch/Batch.java:44](https://github.com/resend/resend-java/blob/e9f7a67ac16fafbe9b0c449b602d73505d4f4bad/src/main/java/com/resend/services/batch/Batch.java#L44), [src/main/java/com/resend/services/batch/Batch.java:56](https://github.com/resend/resend-java/blob/e9f7a67ac16fafbe9b0c449b602d73505d4f4bad/src/main/java/com/resend/services/batch/Batch.java#L56)
Architecture and Components
The system utilizes a service-oriented architecture where the Batch class acts as the primary interface for batch operations. It inherits core functionality from BaseService to handle authentication and mapping.
Core Classes
| Class | Description |
|---|---|
Batch | Main service class that executes batch requests against the /emails/batch endpoint. |
CreateEmailOptions | Data structure containing parameters for an individual email, such as recipients, subject, and content. |
CreateBatchEmailsResponse | The response object containing successful email identifiers and validation errors. |
AbstractBatchEmailsResponse | Base class for batch responses, providing the common data structure for email lists. |
Sources: [src/main/java/com/resend/services/batch/Batch.java:23](https://github.com/resend/resend-java/blob/e9f7a67ac16fafbe9b0c449b602d73505d4f4bad/src/main/java/com/resend/services/batch/Batch.java#L23), [src/main/java/com/resend/services/emails/model/CreateEmailOptions.java:10](https://github.com/resend/resend-java/blob/e9f7a67ac16fafbe9b0c449b602d73505d4f4bad/src/main/java/com/resend/services/emails/model/CreateEmailOptions.java#L10), [src/main/java/com/resend/services/batch/model/CreateBatchEmailsResponse.java:10](https://github.com/resend/resend-java/blob/e9f7a67ac16fafbe9b0c449b602d73505d4f4bad/src/main/java/com/resend/services/batch/model/CreateBatchEmailsResponse.java#L10), [src/main/java/com/resend/services/batch/model/AbstractBatchEmailsResponse.java:15](https://github.com/resend/resend-java/blob/e9f7a67ac16fafbe9b0c449b602d73505d4f4bad/src/main/java/com/resend/services/batch/model/AbstractBatchEmailsResponse.java#L15)
Class Relationships
The following diagram illustrates the relationship between the Batch service and its associated data models.
Explanation: The Batch service extends BaseService and operates on CreateEmailOptions to produce a CreateBatchEmailsResponse.
Sources: [src/main/java/com/resend/services/batch/Batch.java:23](https://github.com/resend/resend-java/blob/e9f7a67ac16fafbe9b0c449b602d73505d4f4bad/src/main/java/com/resend/services/batch/Batch.java#L23), [src/main/java/com/resend/services/batch/model/CreateBatchEmailsResponse.java:10](https://github.com/resend/resend-java/blob/e9f7a67ac16fafbe9b0c449b602d73505d4f4bad/src/main/java/com/resend/services/batch/model/CreateBatchEmailsResponse.java#L10), [src/main/java/com/resend/services/batch/model/AbstractBatchEmailsResponse.java:15](https://github.com/resend/resend-java/blob/e9f7a67ac16fafbe9b0c449b602d73505d4f4bad/src/main/java/com/resend/services/batch/model/AbstractBatchEmailsResponse.java#L15)
Request Execution Flow
When you call the send method, the service serializes the list of email options into a JSON payload. The HttpClient then performs an HTTP POST request to the Resend API.
Explanation: This flow shows the synchronous transformation of Java objects into a network request and back into a structured response.
Sources: [src/main/java/com/resend/services/batch/Batch.java:46-48](https://github.com/resend/resend-java/blob/e9f7a67ac16fafbe9b0c449b602d73505d4f4bad/src/main/java/com/resend/services/batch/Batch.java#L46-L48), [src/main/java/com/resend/core/net/impl/HttpClient.java:119-122](https://github.com/resend/resend-java/blob/e9f7a67ac16fafbe9b0c449b602d73505d4f4bad/src/main/java/com/resend/core/net/impl/HttpClient.java#L119-L122)
Validation Modes
The Batch service supports different validation behaviors based on the provided RequestOptions.
Permissive Mode
If you add the x-batch-validation: permissive header to your RequestOptions, the API allows partial success. Under this mode, some emails in the batch may succeed while others fail validation. The CreateBatchEmailsResponse provides a hasErrors() method to check for failures.
Sources: [src/test/java/com/resend/services/batch/BatchTest.java:79-84](https://github.com/resend/resend-java/blob/e9f7a67ac16fafbe9b0c449b602d73505d4f4bad/src/test/java/com/resend/services/batch/BatchTest.java#L79-L84), [src/main/java/com/resend/services/batch/model/CreateBatchEmailsResponse.java:38-40](https://github.com/resend/resend-java/blob/e9f7a67ac16fafbe9b0c449b602d73505d4f4bad/src/main/java/com/resend/services/batch/model/CreateBatchEmailsResponse.java#L38-L40)
Idempotency
You can provide an idempotency key via RequestOptions to ensure that retrying a batch request does not result in duplicate emails. The HttpClient attaches this key to the Idempotency-Key header.
Sources: [src/main/java/com/resend/core/net/impl/HttpClient.java:229-231](https://github.com/resend/resend-java/blob/e9f7a67ac16fafbe9b0c449b602d73505d4f4bad/src/main/java/com/resend/core/net/impl/HttpClient.java#L229-L231), [src/test/java/com/resend/services/batch/BatchTest.java:95-97](https://github.com/resend/resend-java/blob/e9f7a67ac16fafbe9b0c449b602d73505d4f4bad/src/test/java/com/resend/services/batch/BatchTest.java#L95-L97)
Data Model Specifications
CreateEmailOptions Fields
The CreateEmailOptions class defines the structure for each email within the batch.
| Field | Type | Description |
|---|---|---|
from | String | The sender's email address. |
to | List | The primary recipients. |
subject | String | The email subject line. |
html | String | The HTML content of the email. |
text | String | The plain text content of the email. |
scheduled_at | String | ISO 8601 timestamp for scheduled delivery. |
template | Template | Template configuration for the email. |
Sources: [src/main/java/com/resend/services/emails/model/CreateEmailOptions.java:11-48](https://github.com/resend/resend-java/blob/e9f7a67ac16fafbe9b0c449b602d73505d4f4bad/src/main/java/com/resend/services/emails/model/CreateEmailOptions.java#L11-L48)
Response Data
The CreateBatchEmailsResponse includes the results of the operation.
| Method | Return Type | Description |
|---|---|---|
getData() | List | Returns identifiers for successfully processed emails. |
getErrors() | List | Returns validation errors encountered during processing. |
getErrorCount() | int | Returns the total count of failed emails in the batch. |
Sources: [src/main/java/com/resend/services/batch/model/CreateBatchEmailsResponse.java:30-50](https://github.com/resend/resend-java/blob/e9f7a67ac16fafbe9b0c449b602d73505d4f4bad/src/main/java/com/resend/services/batch/model/CreateBatchEmailsResponse.java#L30-L50), [src/main/java/com/resend/services/batch/model/AbstractBatchEmailsResponse.java:38-40](https://github.com/resend/resend-java/blob/e9f7a67ac16fafbe9b0c449b602d73505d4f4bad/src/main/java/com/resend/services/batch/model/AbstractBatchEmailsResponse.java#L38-L40)
Implementation Example
The following code snippet demonstrates how to initialize the service and send a batch of emails.
// Create a list of email options
List<CreateEmailOptions> batch = new ArrayList<>();
batch.add(CreateEmailOptions.builder()
.from("sender@example.com")
.to("user1@example.com")
.subject("Batch 1")
.text("Hello User 1")
.build());
// Execute batch send
Batch batchService = new Batch("re_123");
CreateBatchEmailsResponse response = batchService.send(batch);
if (response.hasErrors()) {
int failedCount = response.getErrorCount();
// Handle errors
}
Sources: [src/main/java/com/resend/services/batch/Batch.java:44-48](https://github.com/resend/resend-java/blob/e9f7a67ac16fafbe9b0c449b602d73505d4f4bad/src/main/java/com/resend/services/batch/Batch.java#L44-L48), [src/test/java/com/resend/services/batch/BatchTest.java:55-60](https://github.com/resend/resend-java/blob/e9f7a67ac16fafbe9b0c449b602d73505d4f4bad/src/test/java/com/resend/services/batch/BatchTest.java#L55-L60)
The Batch module streamlines bulk email operations by aggregating multiple requests into a single transaction, providing robust error reporting through its response models.