Batch API
Relevant source files
The following files were used as context for generating this wiki page:
The Batch API enables the sending of multiple emails within a single HTTP request. This service reduces the network overhead associated with making individual API calls for large volumes of outbound communication. The system processes these requests through the emails/batch endpoint and returns a collection of results corresponding to each email in the batch.
Sources: tests/Service/Batch.php:21, src/Service/Batch.php
Architecture and Data Flow
The Batch API operates as a specialized service within the Resend PHP SDK. When you initiate a batch send, the Batch service constructs a payload containing an array of email objects. This payload is passed to the HttpTransporter, which manages the PSR-18 compliant HTTP communication with the Resend API.
Request Lifecycle
The following sequence diagram illustrates the process of sending a batch of emails from the client to the API.
The HttpTransporter handles the conversion of PHP arrays into JSON strings and sets the appropriate headers before dispatching the request.
Sources: tests/Transporters/HttpTransporter.php:38, tests/ValueObjects/Transporter/Payload.php:17, tests/Service/Batch.php:23
Key Methods and Parameters
The send() Method
The primary interface for batch operations is the send() method. It accepts an array of email configurations and an optional array of request modifiers.
| Parameter | Type | Description |
|---|---|---|
$payload | array | A list of email objects containing to, from, subject, and text/html. |
$options | array | Optional configuration for headers like idempotency or validation. |
Sources: tests/Service/Batch.php:5-18, tests/Service/Batch.php:23
Batch Configuration Options
You can modify the behavior of the batch request by passing specific keys in the $options array. These options are translated into HTTP headers by the transporter.
| Option Key | Header Generated | Purpose |
|---|---|---|
idempotency_key | Idempotency-Key | Prevents accidental duplicate processing of the same batch. |
batch_validation | x-batch-validation | Defines the validation strictness (e.g., 'permissive'). |
Sources: tests/Service/Batch.php:44, tests/Service/Batch.php:65
Implementation Details
Payload Construction
The Payload value object ensures that the data is correctly formatted for a POST request. For batch operations, it targets the emails/batch path and ensures the body is a valid JSON array.
// Example of how the payload is represented internally
$payload = Payload::create('emails/batch', [
[
'to' => 'user1@example.com',
'from' => 'sales@example.com',
'subject' => 'Hello',
'text' => 'First email',
],
[
'to' => 'user2@example.com',
'from' => 'sales@example.com',
'subject' => 'Hello',
'text' => 'Second email',
]
]);
Sources: tests/ValueObjects/Transporter/Payload.php:17-21, tests/Service/Batch.php:5-18
Response Handling
Upon a successful request, the Batch API returns a Resend\Collection. This collection encapsulates the individual response objects for each email provided in the batch. If the transporter encounters an error (such as a 422 validation error), it throws a Resend\Exceptions\ErrorException containing the specific error code and message returned by the server.
Summary
The Batch API is a high-performance feature of the Resend PHP SDK that allows developers to group multiple email transmissions into a single network call. By utilizing the Batch service and the underlying HttpTransporter, the SDK provides a structured way to handle bulk operations while maintaining support for critical features like idempotency and batch-level validation.