Inboxes & Receiving Emails

Relevant source files

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

• tools/Resend.ApiServer/Controllers/InboxController.cs
• src/Resend/ResendClient.Inboxes.cs
• src/Resend/InboxDraftCreateData.cs
• src/Resend/InboxDraftUpdateData.cs
• tests/Resend.Tests/ResendClientTests.Inboxes.cs
• src/Resend/InboxThreadEmailReplyData.cs
• src/Resend/InboxThreadEmailForwardData.cs
• src/Resend/InboxDraft.cs
• tests/Resend.Webhooks.Tests/InboxWebhookEventTests.cs

Inboxes provide a centralized system for receiving, organizing, and responding to incoming emails. The Resend .NET SDK facilitates full management of inboxes, email threads, organizational labels, and message drafts through the IResend interface.

Inbox Management

You manage the lifecycle of an inbox by creating, retrieving, updating, or deleting inbox resources. Each inbox is associated with an email address and can optionally forward incoming mail to another destination.

• Creation: Define an email address and name to initialize a new inbox.
• Retrieval: Access inbox details using either a unique Guid or the inbox email address.
• Update: Modify the display name (Name) or the sender name (FromName). At least one field is required for an update request to be valid.

The flow shows the standard lifecycle of an inbox resource within the API.
Sources: src/Resend/ResendClient.Inboxes.cs:11-58, tools/Resend.ApiServer/Controllers/InboxController.cs:33-100

Threads and Organization

The system groups related emails into threads to maintain conversation context. You organize these threads using folders and labels.

Thread Folders

Threads exist within specific folders that define their state.

Folder	Description
Inbox	Default location for new incoming messages.
Archive	For completed or processed conversations.
Spam	For unsolicited or malicious messages.
Trash	For deleted conversations.
Sent	Read-only folder containing outbound threads.

Sources: tools/Resend.ApiServer/Controllers/InboxController.cs:427-434, tests/Resend.Tests/InboxRequestTests.cs:256-261

Labels

Labels provide a mechanism for custom categorization. You can create labels with specific names and hex color codes, then apply them to threads.

• Thread Label Limits: A thread can have between 1 and 10 labels assigned during a single addition operation.
• Global Labels: Inboxes maintain a list of available labels that you can manage independently of specific threads.

Sources: tools/Resend.ApiServer/Controllers/InboxController.cs:127-210, src/Resend/ResendClient.Inboxes.cs:79-115

Email Interactions

You interact with received emails by replying to or forwarding them within an existing thread.

Replying to Emails

When you reply to an email, the system manages headers like In-Reply-To and References automatically.

• Validation: You must provide at least one of HtmlBody or TextBody.
• Reserved Headers: You cannot manually set In-Reply-To, References, or Reply-To headers.
• Recipients: The ReplyAll flag determines if the response includes all original recipients or only the sender.

Forwarding Emails

Forwarding creates a new message containing the original content.

• Requirements: You must specify at least one recipient in the To field.
• Attachments: Forwards include original attachments. However, attachments originally sent via a URL cannot be forwarded.

The sequence shows the internal communication during a thread reply operation.
Sources: src/Resend/InboxThreadEmailReplyData.cs:13-75, src/Resend/InboxThreadEmailForwardData.cs:15-84, tools/Resend.ApiServer/Controllers/InboxController.cs:290-326

Inbox Drafts

Drafts represent unsent messages that you can save and modify before delivery.

Draft Types

1. Standalone: A draft that starts a new conversation.
2. Reply: A draft associated with an existing thread and a specific email.

Attachment Handling in Drafts

Draft attachments have stricter requirements than standard email attachments:

• Content-Only: You must provide the raw Content, Filename, and ContentType.
• Restrictions: Drafts do not support Path or ContentId.
• Size Limit: The combined size of all attachments must not exceed 25 MB.

Operation	Behavior
Create	Requires at least one content field (To, Subject, Body, or Attachment).
Update	Replaces specific fields. Assigning null to a field clears it.
Send	Triggers the actual delivery. Optionally accepts custom headers.

Sources: src/Resend/InboxDraftCreateData.cs:11-94, src/Resend/InboxDraftUpdateData.cs:13-108, tools/Resend.ApiServer/Controllers/InboxController.cs:495-502

Inbox Agents

Each inbox can be configured with an Agent that manages automated behaviors. You define the agent's behavior through:

• Instructions: Textual guidance for the agent.
• Tone: Specifies the communication style (e.g., ConciseCasual).
• Actions: A list of permitted operations, such as DraftReply, Archive, or MoveToTrash.

Sources: tools/Resend.ApiServer/Controllers/InboxController.cs:103-124, tests/Resend.Tests/InboxRequestTests.cs:81-125

Webhook Integration

Inboxes emit events via webhooks to notify external systems of state changes.

Event Type	Category	Data Context
inbox.created	Inbox	Full inbox object.
inbox.email.received	ThreadEmail	Thread and Email metadata.
inbox.thread.folder.updated	ThreadFolder	Old and New folder states.
inbox.draft.sent	DraftSent	Draft ID and resulting Email ID.

Sources: tests/Resend.Webhooks.Tests/InboxWebhookEventTests.cs:46-63

The Inbox system integrates receiving capabilities with organizational tools, allowing for complex email workflows managed directly through the .NET SDK. Proper usage requires adhering to recipient limits (max 50) and attachment size constraints (25 MB).