Inbox Threads
Relevant source files
The following files were used as context for generating this wiki page:
Inbox Threads group related email communications within a specific Inbox. This system allows you to manage conversations collectively, apply labels, move groups of emails between folders, and perform granular searches across conversation histories.
The Thread service acts as the primary interface for thread management, providing sub-services for handling individual emails and labels associated with those threads.
Sources: src/Service/Inboxes/Thread.php:12-25, src/Inboxes/Thread.php:5-25
Architecture and Service Structure
The Inbox system is hierarchical. The Resend\Service\Inbox service exposes a threads property which provides access to thread-specific operations. Within the Thread service, nested services manage specialized child resources: emails and labels.
Service Hierarchy Diagram
This diagram illustrates the relationship between the parent Inbox service and the Thread management components.
Data Model
A Thread resource represents the metadata and state of a conversation. It tracks the number of emails, the latest participants, and the current folder location.
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the thread. |
object | string|null | Object type (inbox_thread). |
subject | string|null | The subject line of the conversation. |
folder | enum | Location: inbox, archive, spam, sent, or trash. |
read | bool | True only if every email in the thread is marked as read. |
email_count | int|null | The total number of emails contained in the thread. |
labels | array | List of label objects (id, name, color) attached to the thread. |
matched_email_id | string|null | Present in search results; identifies the specific email matching the query. |
Sources: src/Inboxes/Thread.php:7-24, tests/Fixtures/Inboxes/Thread.php:5-20
Thread Operations
Retrieval and Filtering
You list threads within an inbox using the list method. The results are ordered by the most recently active thread first. You can filter threads by folder, read status, or specific labels.
$threads = $resend->inboxes->threads->list('inbox_id', [
'folders' => ['inbox', 'sent'],
'read' => false,
'limit' => 10,
]);
Sources: src/Service/Inboxes/Thread.php:39-55, tests/Service/Inboxes/Thread.php:9-25
Searching
The search method allows for complex queries across threads. Filters such as query, from, to, and has_attachment must all match the same email within a thread for that thread to be returned.
Lifecycle Management
Threads can be moved between folders or marked as read/unread using the update method. Removing a thread via the remove method moves it to the trash folder and schedules it for permanent deletion after 30 days.
Sources: src/Service/Inboxes/Thread.php:123-157
Sub-Resource Management
Thread Emails
The emails sub-service manages individual messages within a thread. You can list all emails in a thread, retrieve a single email, reply to a specific message, or forward a message.
- Reply: Creates a new outbound email in the thread. You can use
reply_allto include all original recipients. - Forward: Sends the content of an existing email to new recipients.
Sources: src/Service/Inboxes/Threads/Email.php:15-85, tests/Service/Inboxes/Threads/Email.php:40-63
Thread Labels
Labels are managed through the labels sub-service.
- Add: Appends new labels to the thread without removing existing ones.
- Set: Replaces all current labels on the thread with a new set (or clears them if an empty array is provided).
- Remove: Detaches a specific label from the thread.
Sources: src/Service/Inboxes/Threads/Label.php:15-68, tests/Service/Inboxes/Threads/Label.php:20-56
Summary
Inbox Threads provide a structured way to handle complex email conversations in PHP applications. By leveraging the Thread service and its associated sub-services, you can implement full-featured communication interfaces that support conversation grouping, multi-parameter searching, and organized label management.