Batch Email Processing

Batch Email Processing allows you to send multiple emails in a single API request. This system optimizes network overhead and provides options for managing validation behavior and request idempotency. The SDK handles the serialization of multiple SendEmailRequest objects and processes a structured response containing success data and optional error details.

Sources: batch.go:1-93, examples/send_batch_email.go:13-33

Architecture and Data Flow

The BatchSvc interface defines the operations for batch processing. The implementation, BatchSvcImpl, uses the Resend client to execute HTTP POST requests to the emails/batch endpoint.

Request Flow

The following diagram illustrates the sequence of actions when a user initiates a batch send operation.

The flow ensures that validation modes are checked before the request is constructed.
Sources: batch.go:78-124, batch_test.go:167-195

Key Components and Data Structures

BatchSendEmailOptions

This structure configures the behavior of the batch request.

Sources: batch.go:29-37, examples/send_batch_email.go:41-43

Validation Modes

The system supports two distinct validation behaviors defined by the BatchValidationMode type:

1. Strict: This is the default mode. The API only sends the batch if every email in the request is valid.
2. Permissive: The API processes all emails in the batch. Valid emails are sent, and invalid ones return error details in the response.

Sources: batch.go:10-18, examples/send_batch_email.go:52-81

Response Structure

The BatchEmailResponse contains the outcome for every email in the request.

The Errors slice is populated when using BatchValidationPermissive, mapping failure messages to the original index of the email in the request.
Sources: batch.go:48-60, batch_test.go:48-65

Service Implementation

The BatchSvc provides three primary methods for interaction:

• Send(params): Sends a batch using default background context.
• SendWithContext(ctx, params): Sends a batch with a provided context.
• SendWithOptions(ctx, params, options): Sends a batch with specific configuration for idempotency or validation.

Internal Logic

When SendWithOptions is called, the service performs the following steps:

1. Verifies the BatchValidationMode is valid (Strict or Permissive).
2. Constructs the request via NewRequestWithOptions.
3. Injects the Idempotency-Key and x-batch-validation headers into the HTTP request if specified.
4. Decodes the response into a BatchEmailResponse object.

Sources: batch.go:62-124, batch_test.go:197-233

Idempotency and Headers

Idempotency ensures that retrying a request with the same key within 24 hours returns the same result without double-sending emails. The SDK maps BatchSendEmailOptions to specific HTTP headers.

Sources: batch.go:39-46, batch_test.go:137-145, emails_test.go:174-192

Summary

Batch Email Processing in the Resend Go SDK provides a robust way to handle high-volume email delivery. By utilizing the BatchSvc, you can manage large sets of emails while controlling error handling via BatchValidationMode and ensuring request reliability with idempotency keys. The implementation abstracts the complex task of header management and response mapping into a simplified interface.

Sources: batch.go:1-124, examples/send_batch_email.go:1-105