Inboxes & Email Threads Management
Relevant source files
The following files were used as context for generating this wiki page:
The Inboxes and Email Threads Management system handles the receipt and transmission of emails at specific addresses on verified domains. This module provides tools to manage conversations through threads, organize communication via labels and folders, and automate responses using inbox agents. It also supports draft lifecycle management, including creation, updating, and asynchronous sending.
Sources: resend/inboxes/_inboxes.py:16-20, resend/inboxes/threads/_inbox_threads.py:84-87
Inbox Core Management
An Inbox represents a specific email address on a domain belonging to a team. The Inboxes class provides methods to create, list, retrieve, update, and remove these entities.
Key Operations
- Create: Provisions a new inbox. If the
forwardingparameter isTrue, the system generates areceiving_addressto allow mail receipt without MX record configuration. - List: Retrieves a paginated list of inboxes for the team, ordered newest first.
- Get: Retrieves full details of a single inbox using either its unique ID or its email address.
- Update: Modifies the internal name or the display "From" name shown to recipients.
Sources: resend/inboxes/_inboxes.py:127-217
Inbox Data Structure
| Field | Type | Description |
|---|---|---|
id | str | Unique identifier or email address. |
email_address | str | The primary address of the inbox. |
name | str | Internal name for organization. |
from_name | str | Name seen by recipients. |
receiving_address | Optional[str] | Address provided when forwarding is enabled. |
Sources: resend/inboxes/_inboxes.py:44-93
Email Threads and Search
The system organizes emails into conversations called threads. The InboxThreads module manages these groups, allowing for folder-based organization and advanced searching.
This diagram shows how different search parameters combine to produce filtered thread results. Sources: resend/inboxes/threads/_inbox_threads.py:171-196
Thread Folders
Threads exist within specific folders that categorize their status:
inbox: Standard incoming mail.archive: Completed conversations.sent: Outgoing mail generated by the inbox.spam: Filtered junk mail.trash: Deleted threads scheduled for removal in 30 days.
Sources: resend/inboxes/threads/_inbox_threads.py:21-27, resend/inboxes/threads/_inbox_threads.py:145-148
Thread Email Operations
Individual messages within a thread are managed through InboxThreadEmails. This module allows users to list messages chronologically, fetch specific content (HTML/Text), and perform outbound actions like replying or forwarding.
Replying and Forwarding
The system supports direct responses without manually managing message headers.
- Reply: Automatically sets
In-Reply-ToandReferencesheaders. Ifreply_allis enabled, it includes all original recipients. - Forward: Quotes the original message under a forwarded-message banner and includes original attachments.
Sources: resend/inboxes/threads/emails/_inbox_thread_emails.py:237-279
This diagram illustrates the flow of sending a reply within an existing thread. Sources: resend/inboxes/threads/emails/_inbox_thread_emails.py:237-257
Draft Management
InboxDrafts manages unsent messages. Drafts are categorized by InboxDraftType as either standalone (starting a new thread) or reply (targeting an existing conversation).
Draft Lifecycle
- Create: Requires at least one content field (subject, body, or attachments). Reply drafts must include
thread_idandreply_to_email_id. - Update: Modifies recipients, subject, or bodies. Sending
attachmentsreplaces all existing files on the draft. - Send: Dispatches the draft as a live email. This operation is idempotent if an
idempotency_keyis provided in the options.
Sources: resend/inboxes/drafts/_inbox_drafts.py:220-315, resend/inboxes/drafts/_inbox_draft.py:9-13
Draft Constraints
| Constraint | Value | Source |
|---|---|---|
| Max Recipients | 50 (Combined To, CC, BCC) | _inbox_drafts.py:100 |
| Max Subject Length | 2000 characters | _inbox_drafts.py:126 |
| Max Attachment Size | 25 MB total | _inbox_drafts.py:136 |
| Deletion Policy | Standard API delete | _inbox_drafts.py:284 |
Event Handling and Webhooks
The system emits various webhook events to notify external services of changes in inboxes, threads, or drafts.
Common Inbox Events
inbox.email.received: Triggered when a new inbound message arrives.inbox.thread.folder.updated: Triggered when a thread is moved (e.g., frominboxtoarchive).inbox.draft.sent: Triggered when an unsent draft successfully transitions to a queued email.
Sources: resend/webhooks/_webhook_event.py:440-511
Conclusion
The Inboxes and Email Threads Management module provides a comprehensive API for handling professional email workflows. It bridges the gap between raw SMTP delivery and structured conversation management by providing native support for threading, draft persistence, and automated organization through folders and labels. Through idempotent operations and extensive webhook support, it ensures reliable integration for complex communication platforms.
Sources: resend/inboxes/_inboxes.py:16-20, resend/inboxes/drafts/_inbox_drafts.py:298-315