Inboxes and Agents
Relevant source files
The following files were used as context for generating this wiki page:
The Inbox system manages email addresses that send and receive mail on your domains. It provides a structured environment for handling communications through threads, drafts, and automated agents.
The Agent component provides automated intelligence for specific inboxes. You configure an agent with instructions, a specific writing tone, and a set of permitted actions to manage incoming threads automatically.
Sources: src/Service/Inbox.php, src/Service/Inboxes/Agent.php
Service Architecture
The Resend\Service\Inbox class serves as the primary entry point for inbox management. It aggregates specialized sub-services to handle different aspects of the inbox lifecycle.
Component Hierarchy
This diagram shows the relationship between the main Inbox service and its specialized child services.
Sources: src/Service/Inbox.php:12-32, src/Service/Inboxes/Thread.php:14-23
Inbox Management
You create an inbox to handle mail for a specific address. The system identifies inboxes using either a unique ID or the percent-encoded email address.
Data Model: Inbox Resource
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the inbox |
email_address | string | The address assigned to the inbox |
receiving_address | string | null | Address for mail forwarding if enabled |
unread | int | Count of unread threads in the folder |
drafts | int | null | Number of unsent drafts |
last_received | string | null | Timestamp of the newest received email |
Sources: src/Inbox.php:7-22, src/Service/Inbox.php:82-91
Inbox Agents
Agents automate thread management based on pre-defined instructions. If an inbox has no configured agent, the system returns null values for instructions and tone.
Agent Configuration
An agent operates based on three primary configurations:
- Instructions: Text guidelines the agent follows when handling threads.
- Tone: The writing style used in generated content (e.g.,
concise_professional,expanded_casual). - Actions: A defined list of operations the agent can execute.
Permitted Agent Actions
| Action | Description |
|---|---|
draft_reply | Creates a draft response to a thread |
forward_thread | Forwards the conversation to another address |
add_labels | Attaches specific labels to the thread |
assign_thread | Assigns the thread to a team member |
archive | Moves the thread to the archive folder |
move_to_trash | Sends the thread to the trash folder |
Sources: src/Inboxes/Agent.php:12-14, src/Service/Inboxes/Agent.php:18-42
Thread and Folder Logic
Threads organize related emails. The system places threads into specific folders and manages their read/unread status.
Thread Workflow
The flow shows how threads move between folders and how their read status is updated. Moving a thread out of trash restores it and cancels the deletion deadline.
Sources: src/Service/Inboxes/Thread.php:118-132, src/Inboxes/Thread.php:22-25
Drafts and Replies
The Draft service manages unsent messages. Drafts are categorized by their relationship to existing conversations.
Draft Types
- Standalone: Starts a completely new thread.
- Reply: Responds to a specific email within an existing thread.
When you send a draft, the service returns an Email resource containing the email_id of the outbound message.
Sources: src/Inboxes/Draft.php:12-25, src/Service/Inboxes/Draft.php:154-165
Conclusion
The Inboxes and Agents system provides a robust framework for managing domain-based email communications. By combining manual thread management with AI-driven agents, it allows for scalable handling of high-volume email workflows.