Email Management
Relevant source files
The following files were used as context for generating this wiki page:
Email Management provides the core functionality for sending, receiving, and tracking emails through the Resend API. The system handles individual messages, batch transmissions, scheduled delivery, and inbound email processing. It supports various content formats, including plain text, HTML, and React components.
Outbound Email Operations
The Emails class serves as the primary interface for outbound operations. It manages the lifecycle of an email from initial creation to delivery tracking.
Sending Individual Emails
You send emails using the send or create methods. If you provide a react component in the payload, the system renders it to HTML before transmission. The API supports standard fields like to, from, subject, and bcc, alongside advanced options like custom headers and tags.
Sources: src/emails/emails.ts:47-61, src/emails/interfaces/create-email-options.interface.ts:47-115
This diagram shows the logic flow when initiating a single email request, including the optional React rendering step.
Batch Operations
The Batch module allows sending up to 100 emails in a single API call. You choose between two validation modes:
- Strict: Fails the entire batch if any email is invalid.
- Permissive: Processes valid emails and returns a list of errors for invalid ones.
Sources: src/batch/batch.spec.ts:40-66, src/batch/batch.spec.ts:258-290
Email Management Features
| Feature | Description | Source |
|---|---|---|
| Scheduling | Set scheduledAt to delay delivery. | src/emails/emails.ts:94-106 |
| Cancellation | Cancel a scheduled email using its ID. | src/emails/emails.ts:108-116 |
| Sharing | Generate a public URL for a sent email. | src/emails/emails.ts:118-128 |
| Idempotency | Prevent duplicate sends using an idempotencyKey. | src/emails/interfaces/create-email-options.interface.ts:121-123 |
Inbound Email Management
The Receiving module manages emails sent to your Resend-managed inboxes. It provides methods to retrieve, list, and forward inbound communications.
Retrieving Inbound Content
The receiving.get method fetches full details for an inbound email, including raw bytes and attachment metadata. If you require a specific format, you can set the html_format parameter to cid.
Sources: src/emails/receiving/receiving.spec.ts:47-87, src/emails/receiving/receiving.spec.ts:145-175
Forwarding Inbound Emails
You forward received emails in two distinct modes:
- Passthrough (Default): Sends the email with original content, including decoded charset and original attachments.
- Wrapped: Attaches the original message as a
.emlfile to a new email.
Sources: src/emails/receiving/receiving.spec.ts:436-476, src/emails/receiving/receiving.spec.ts:588-638
The sequence diagram illustrates the multi-step process required to forward a received email, including fetching metadata and downloading raw content.
Inbox Threads and Drafts
Email Management extends into collaborative inbox features, allowing you to manage conversations via threads and prepare messages via drafts.
Thread Operations
Threaded email management allows you to reply to or forward specific messages within an existing conversation.
- Reply: Sends a response to a specific message ID in a thread. You can set
replyAllto include all previous recipients. - Forward: Sends a copy of a thread message to new recipients.
Sources: src/inboxes/threads/emails/emails.spec.ts:89-130, src/inboxes/threads/emails/emails.spec.ts:233-270
Draft Management
Drafts allow you to store standalone messages or thread replies before sending.
- Standalone: Created without a thread reference.
- Threaded: Created with
threadIdandreplyToEmailIdto maintain conversation context. - Attachments: You can add, update, or remove attachments by passing an array or
null.
Sources: src/inboxes/drafts/drafts.spec.ts:98-130, src/inboxes/drafts/drafts.spec.ts:248-275
Analytics and Metrics
The metrics method retrieves delivery and engagement data. You can aggregate data using various dimensions and filters.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
startDate | string | The start date for the metric range. |
endDate | string | The end date for the metric range. |
granularity | string | Data grouping (e.g., daily). |
dimensions | array | Grouping criteria: period, domain, email, broadcast. |
metrics | array | Data points: sent, delivered, open_rate, click_rate. |
Sources: src/emails/emails.ts:130-142, src/emails/emails.spec.ts:536-578
This graph represents the filter dimensions available when querying email performance metrics.
Conclusion
Email Management provides a unified interface for the entire email lifecycle. It integrates high-level abstractions like React rendering and batching with low-level capabilities like raw RFC822 byte processing and conversation threading. This structure ensures developers can handle simple notifications and complex inbox management within the same system.