Batch Sending & Scheduling
Relevant source files
The following files were used as context for generating this wiki page:
Batch Sending and Scheduling allow applications to manage large volumes of outgoing communications efficiently. The resend-dotnet library provides mechanisms to send multiple emails in a single request and defer the delivery of emails or broadcasts to a specific future time. These features reduce the number of API round-trips and provide control over communication timing.
Batch Sending
The library supports sending groups of emails through the EmailBatchAsync method. This operation targets the /emails/batch endpoint. You can transmit a collection of EmailMessage objects, and the API processes them according to the specified validation mode.
Validation Modes
The batch operation supports two validation modes that dictate how the API handles individual message failures within a batch:
- Strict: The API sends emails only if all messages in the batch are valid. If one message fails validation, the entire batch is rejected.
- Permissive: The API attempts to send all valid messages and returns specific error information for invalid ones.
Sources: [src/Resend/IResend.cs:89-120](https://github.com/resend/resend-dotnet/blob/9eacf6bade3c698df5e42d3a6ed6056b93a5e66d/src/Resend/IResend.cs#L89-L120), [src/Resend/ResendClient.cs:122-160](https://github.com/resend/resend-dotnet/blob/9eacf6bade3c698df5e42d3a6ed6056b93a5e66d/src/Resend/ResendClient.cs#L122-L160)
Idempotency in Batches
To prevent duplicate email delivery during network retries, you can provide an idempotencyKey. The ResendClient includes this key in the Idempotency-Key HTTP header. The Resend API uses this key to ensure that a specific batch is processed only once within a 24-hour window.
Sources: [src/Resend/ResendClient.cs:105-115](https://github.com/resend/resend-dotnet/blob/9eacf6bade3c698df5e42d3a6ed6056b93a5e66d/src/Resend/ResendClient.cs#L105-L115), [src/Resend/IResend.cs:99-105](https://github.com/resend/resend-dotnet/blob/9eacf6bade3c698df5e42d3a6ed6056b93a5e66d/src/Resend/IResend.cs#L99-L105)
Batch Sending Flow
The following diagram illustrates the sequence of a batch sending request.
The sequence diagram shows the interaction between the application, SDK, and API during a batch email request.
Sources: [src/Resend/ResendClient.cs:122-160](https://github.com/resend/resend-dotnet/blob/9eacf6bade3c698df5e42d3a6ed6056b93a5e66d/src/Resend/ResendClient.cs#L122-L160)
Scheduling and Management
Scheduling allows you to specify a future date and time for email or broadcast delivery. The library provides methods to schedule new communications, reschedule pending ones, and cancel scheduled tasks.
Email Rescheduling and Cancellation
You can modify the delivery time of a previously sent email that has not yet been delivered. The EmailRescheduleAsync method sends a Patch request to the /emails/{emailId} endpoint.
| Action | Method | Source File |
|---|---|---|
| Reschedule | EmailRescheduleAsync | [src/Resend/ResendClient.cs:163-174](https://github.com/resend/resend-dotnet/blob/9eacf6bade3c698df5e42d3a6ed6056b93a5e66d/src/Resend/ResendClient.cs#L163-L174) |
| Cancel | EmailCancelAsync | [src/Resend/ResendClient.cs:177-183](https://github.com/resend/resend-dotnet/blob/9eacf6bade3c698df5e42d3a6ed6056b93a5e66d/src/Resend/ResendClient.cs#L177-L183) |
Sources: [src/Resend/Payloads/EmailRescheduleRequest.cs](https://github.com/resend/resend-dotnet/blob/9eacf6bade3c698df5e42d3a6ed6056b93a5e66d/src/Resend/Payloads/EmailRescheduleRequest.cs), [src/Resend/IResend.cs:134-142](https://github.com/resend/resend-dotnet/blob/9eacf6bade3c698df5e42d3a6ed6056b93a5e66d/src/Resend/IResend.cs#L134-L142)
Broadcast Scheduling
Broadcasts are sent to specific audience segments. You can trigger them immediately or schedule them for the future using the BroadcastScheduleAsync method. This method populates a BroadcastScheduleRequest containing the MomentSchedule property.
Sources: [src/Resend/Payloads/BroadcastScheduleRequest.cs](https://github.com/resend/resend-dotnet/blob/9eacf6bade3c698df5e42d3a6ed6056b93a5e66d/src/Resend/Payloads/BroadcastScheduleRequest.cs), [src/Resend/ResendClient.cs:337-346](https://github.com/resend/resend-dotnet/blob/9eacf6bade3c698df5e42d3a6ed6056b93a5e66d/src/Resend/ResendClient.cs#L337-L346)
The flowchart describes the decision path for immediate versus scheduled broadcasts.
Sources: [src/Resend/ResendClient.cs:326-346](https://github.com/resend/resend-dotnet/blob/9eacf6bade3c698df5e42d3a6ed6056b93a5e66d/src/Resend/ResendClient.cs#L326-L346)
Asynchronous Reliability
For critical workflows, batch sending and scheduling are often combined with background job libraries like Hangfire. This ensures durability against transient API failures or network interruptions.
- Job Enqueueing: The application enqueues an email job.
- Persistence: Hangfire serializes the
EmailMessage(keeping payloads small is recommended). - Execution: The Hangfire server invokes
IResend.EmailSendAsync. - Retry Logic: If the API returns a transient error, the job is retried automatically.
Sources: [examples/AsyncHangfire/README.md](https://github.com/resend/resend-dotnet/blob/9eacf6bade3c698df5e42d3a6ed6056b93a5e66d/examples/AsyncHangfire/README.md)
Data Models Summary
The following table summarizes the primary data structures used in batch and scheduling operations.
| Class | Purpose | Key Properties |
|---|---|---|
EmailBatchResponse | Represents the API result of a batch request. | Data (List of Object IDs) |
EmailRescheduleRequest | Payload for updating an email's delivery time. | MomentSchedule (DateTimeOrHuman) |
BroadcastScheduleRequest | Payload for scheduling broadcasts. | MomentSchedule (DateTime) |
EmailMessage | The individual email content for batches. | From, To, Subject, HtmlBody |
Sources: [src/Resend/EmailBatchResponse.cs](https://github.com/resend/resend-dotnet/blob/9eacf6bade3c698df5e42d3a6ed6056b93a5e66d/src/Resend/EmailBatchResponse.cs), [src/Resend/Payloads/EmailRescheduleRequest.cs](https://github.com/resend/resend-dotnet/blob/9eacf6bade3c698df5e42d3a6ed6056b93a5e66d/src/Resend/Payloads/EmailRescheduleRequest.cs), [src/Resend/Payloads/BroadcastScheduleRequest.cs](https://github.com/resend/resend-dotnet/blob/9eacf6bade3c698df5e42d3a6ed6056b93a5e66d/src/Resend/Payloads/BroadcastScheduleRequest.cs)
Batch Sending and Scheduling provide the scalability and flexibility required for complex communication requirements. By leveraging validation modes and idempotency keys, you ensure reliable delivery across large datasets. Scheduling further enables precise control over when messages reach their recipients.