Inboxes & Receiving APIs
Relevant source files
The following files were used as context for generating this wiki page:
The Inboxes & Receiving APIs enable Resend users to manage email communication directly within their domains. These services support creating virtual inboxes, managing threaded conversations, handling inbound email events via webhooks, and interacting with draft messages for coordinated replies.
The InboxesSvc provides full lifecycle management for inboxes, labels, and threads, while the ReceivingSvc handles specific inbound email processing and forwarding. These components work together with the Events system to notify applications of new inbound mail.
Sources: src/inboxes.rs:27-32, src/receiving.rs:17-21, src/lib.rs:125-131
Inbox Management
An inbox represents a specific email address on a managed domain. It tracks unread thread counts, active drafts, and the last time email was received.
Core Inbox Lifecycle
You create an inbox using CreateInboxOptions, which specifies the email address and optional forwarding settings. If forwarding is enabled, Resend provisions a receiving address to allow mail reception without immediate MX record configuration.
The diagram shows the lifecycle of an Inbox resource from creation to management.
Sources: src/inboxes.rs:400-450, src/inboxes.rs:33-85
Inbox Agent and Configuration
Inboxes include an "Agent" that can perform automated actions such as drafting replies, archiving threads, or moving items to trash based on specified instructions and tone presets.
| Field | Type | Description |
|---|---|---|
instructions | Option<String> | Directions the agent follows for thread handling (Max 4000 chars). |
tone | InboxAgentTone | Tone presets: concise_casual, expanded_professional, etc. |
actions | Vec<InboxAgentAction> | Allowed actions: draft_reply, mark_as_spam, archive, etc. |
Sources: src/inboxes.rs:524-540, src/inboxes.rs:543-575
Thread and Email Interaction
Communication in an inbox is organized into threads. A thread groups related InboxThreadEmail messages and carries metadata like labels and read/unread status.
Thread Operations
Threads are moved between folders (inbox, archive, spam, sent, trash). Moving a thread to trash schedules it for permanent deletion in 30 days.
The sequence shows a typical interaction for listing and moving threads to different folders.
Sources: src/inboxes.rs:176-258, src/inboxes.rs:693-718
Replying and Forwarding
The API allows immediate replies or forwarding of existing emails within a thread. These actions support custom headers and attachments. Both operations utilize Idempotent<T> to prevent duplicate sends during retries.
- Reply: Uses
ReplyInboxThreadEmailOptions. It supportsreply_alllogic to include CC recipients from the original message. - Forward: Uses
ForwardInboxThreadEmailOptions. It requires at least one recipient address in thetofield.
Sources: src/inboxes.rs:341-395, src/inboxes.rs:818-875, src/inboxes.rs:904-955
Drafts
Drafts allow for asynchronous message preparation. They can be Standalone (starting a new thread) or Reply (associated with an existing thread and email).
Draft Attributes
When updating a draft, omitting a field leaves it unchanged, while explicitly providing null via Nullable<T> clears the field. Total attachment content for a draft cannot exceed 25 MB.
Sources: src/inboxes.rs:983-1025, src/inboxes.rs:1140-1175
Inbound Email Events
Inbound activities trigger webhooks described in the events module. These events notify your application when inboxes are modified or when new mail arrives.
Inbox Event Structure
Inbox events (InboxEvent) include a source field indicating whether the change was made via the API, Dashboard, Agent, or the internal System.
The class diagram represents the relationship between high-level inbox events and their payload bodies.
Sources: src/events.rs:322-386, src/events.rs:490-502
Data Models
Inbox Schemas
| Entity | ID Type | Key Fields |
|---|---|---|
| Inbox | InboxId | email_address, unread, drafts, last_received |
| InboxThread | InboxThreadId | subject, email_count, has_attachment, folder |
| InboxLabel | InboxLabelId | name, color (#RRGGBB hex) |
| InboxDraft | InboxDraftId | type, to, subject, thread_id |
Sources: src/inboxes.rs:400-435, src/inboxes.rs:693-718, src/inboxes.rs:595-605
Summary
The Inboxes & Receiving APIs provide a robust framework for managing domain-based email interaction. By leveraging InboxesSvc for stateful management of threads and drafts, alongside the events system for real-time inbound notifications, developers can build complex email-native applications. These services include built-in support for automated agents, categorization through labels, and transactional safety via idempotency keys.
Sources: src/inboxes.rs:27-32, src/events.rs:322-340, CHANGELOG.md:12-14