Emails API

Relevant source files

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

• src/emails.rs
• src/batch.rs
• src/lib.rs
• src/events.rs
• src/inboxes.rs
• README.md

The Emails API module manages the creation, transmission, and tracking of electronic mail through the Resend platform. It provides developers with tools to send individual messages, trigger batch deliveries, schedule future transmissions, and retrieve delivery metrics.

The module encapsulates functionality for handling attachments, tags, and custom headers while supporting both synchronous and asynchronous execution modes. It serves as the primary interface for communication within the resend-rust crate, integrating with other systems like Inboxes and Events for comprehensive lifecycle management.
Sources: src/lib.rs:56-72, src/emails.rs:20-22

Core Services and Architecture

The system organizes email operations into two primary service structures: EmailsSvc for individual and administrative email tasks, and BatchSvc for high-volume operations.

EmailsSvc

EmailsSvc handles the standard lifecycle of an email, including sending, retrieving, updating, and canceling scheduled messages. It interacts directly with the /emails endpoints of the Resend API.
Sources: src/emails.rs:23-113

BatchSvc

BatchSvc manages the /emails/batch endpoint, allowing the transmission of up to 100 emails in a single API call. It supports two validation modes:

• Strict: Rejects the entire batch if any single email fails validation.
• Permissive: Processes all valid emails in the batch and returns specific errors for invalid ones.
  Sources: src/batch.rs:16-80

The following diagram illustrates the high-level request flow for sending an email:

Diagram shows the logic path from a user request to the API call, including idempotency handling.
Sources: src/emails.rs:28-44, src/batch.rs:50-56

Data Structures and Configuration

The API uses structured options to define email properties and delivery behavior.

CreateEmailBaseOptions

This structure contains all required components for sending an email. Fields include sender and recipient addresses, subject, body content (HTML or text), and metadata like tags and headers.
Sources: src/emails.rs:136-169

Field	Type	Description
from	String	Sender email address (e.g., Name <sender@domain.com>).
to	Vec<String>	Recipient email addresses (Max 50).
subject	String	Email subject line.
html	Option<String>	The HTML version of the message.
text	Option<String>	The plain text version of the message.
scheduled_at	Option<String>	ISO 8601 timestamp for scheduled sending.
attachments	Option<Vec<CreateAttachment>>	File attachments (max 40MB total).
Sources: src/emails.rs:136-169

Email Metrics

The metrics system tracks delivery performance through various dimensions and metrics.
Sources: src/emails.rs:608-626

Diagram represents the relationship between the metrics response and its supporting enums.
Sources: src/emails.rs:555-562, src/emails.rs:589-594, src/emails.rs:608-626

Operations and Procedures

Sending Individual Emails

You can send emails by providing a CreateEmailBaseOptions object to the send method.

1. Define the sender, recipients, and subject using CreateEmailBaseOptions::new.
2. Attach content using builder methods like with_html or with_text.
3. Optionally add an idempotency key using with_idempotency_key.
4. Call resend.emails.send(email).await.
   Sources: src/emails.rs:28-44, src/emails.rs:175-188

Batch Email Transmission

Batching reduces HTTP overhead for multiple recipients.

1. Create a Vec<CreateEmailBaseOptions>.
2. Choose a BatchValidation mode (Strict or Permissive).
3. Call resend.batch.send_with_batch_validation(emails, mode).await.
   Sources: src/batch.rs:16-65

Attachment Management

Attachments are limited to a total of 40MB per email.

• From Content: Provide a Vec<u8> to CreateAttachment::from_content.
• From Path: Provide a URL string to CreateAttachment::from_path.
• Inline Reference: Use with_content_id to refer to the attachment in HTML via the cid: prefix.
  Sources: src/emails.rs:325-350

Email Lifecycle Tracking

The API tracks the state of every email via the EmailEvent enum. This status is returned when retrieving an email or via webhooks.
Sources: src/emails.rs:444-469

Event Type	Description
Sent	The email was sent successfully.
Delivered	The email reached the recipient's mail server.
Bounced	The recipient's mail server rejected the email.
Opened	The recipient opened the message.
Clicked	The recipient clicked a link within the message.
Scheduled	The email is queued for future delivery.
Failed	The email failed to be sent.
Sources: src/emails.rs:444-469

Integration with Events

The Emails API provides the data source for the events module. When an email status changes, Resend generates an EmailEvent containing a EmailBody. This body includes the email_id, message_id, and any relevant status-specific data such as bounce reasons or click coordinates.
Sources: src/events.rs:293-311

Diagram shows the sequence from an application sending an email to a webhook event being parsed.
Sources: src/emails.rs:28-44, src/events.rs:228-241

The Emails API module is essential for automated communications, providing robust handling for both simple notifications and complex batch marketing campaigns. Its tight integration with metrics and events ensures that developers can monitor and respond to the delivery lifecycle in real-time.