Query, manage, and interact with email threads and individual messages within inboxes.

Threads & Messages

The Threads API provides access to email conversations (threads) and individual messages within your inboxes.

Overview

Email threads group related messages together, making it easy to track conversations:

Messages with the same Message-ID chain are grouped into threads
Each thread has a status: active, archived, spam, or trash
Messages can be marked as read/unread
Full MIME content is available for each message

Base URL

/api/email/inboxes/:inboxId/threads

Thread Endpoints

List Threads

Retrieve all threads for a specific inbox.

GET /api/email/inboxes/:inboxId/threads

Query Parameters:

Parameter	Type	Description
`status`	string	Filter by: `active`, `archived`, `spam`, `trash`
`unread`	boolean	Filter by read status
`from`	string	Filter by sender email
`search`	string	Search in subject and body
`limit`	number	Number of results (default: 20)
`offset`	number	Pagination offset

Response:

{
  "threads": [
    {
      "id": "thd_abc123def",
      "inboxId": "inb_123456789",
      "subject": "Support Request #1234",
      "status": "active",
      "messageCount": 3,
      "unreadCount": 1,
      "lastMessageAt": "2024-01-15T14:30:00Z",
      "participants": [
        { "name": "John Doe", "email": "john@example.com" },
        { "name": "Support Team", "email": "support@yourdomain.com" }
      ],
      "preview": "Hi, I'm having trouble with...",
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Get Thread

Retrieve a specific thread with all its messages.

GET /api/email/inboxes/:inboxId/threads/:threadId

Response:

{
  "id": "thd_abc123def",
  "inboxId": "inb_123456789",
  "subject": "Support Request #1234",
  "status": "active",
  "messageCount": 3,
  "unreadCount": 1,
  "participants": [
    { "name": "John Doe", "email": "john@example.com" },
    { "name": "Support Team", "email": "support@yourdomain.com" }
  ],
  "messages": [
    {
      "id": "msg_xyz789abc",
      "threadId": "thd_abc123def",
      "messageId": "<abc123@example.com>",
      "from": { "name": "John Doe", "email": "john@example.com" },
      "to": [{ "name": "Support Team", "email": "support@yourdomain.com" }],
      "subject": "Support Request #1234",
      "body": { "text": "Hi, I'm having trouble...", "html": "<p>Hi...</p>" },
      "attachments": [],
      "isRead": true,
      "receivedAt": "2024-01-15T10:00:00Z"
    }
  ],
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T14:30:00Z"
}

Update Thread Status

Change the status of a thread.

PATCH /api/email/inboxes/:inboxId/threads/:threadId

Request Body:

{
  "status": "archived",
  "isRead": true
}

Response:

{
  "id": "thd_abc123def",
  "status": "archived",
  "unreadCount": 0,
  "updatedAt": "2024-01-15T15:00:00Z"
}

Delete Thread

Move a thread to trash or permanently delete it.

DELETE /api/email/inboxes/:inboxId/threads/:threadId

Query Parameters:

Parameter	Type	Description
`permanent`	boolean	Permanently delete (default: false)

Response:

{
  "success": true,
  "message": "Thread moved to trash",
  "threadId": "thd_abc123def"
}

Message Endpoints

Get Message

Retrieve a specific message by ID.

GET /api/email/inboxes/:inboxId/messages/:messageId

Response:

{
  "id": "msg_xyz789abc",
  "threadId": "thd_abc123def",
  "messageId": "<abc123@example.com>",
  "inReplyTo": "<parent456@example.com>",
  "references": ["<parent456@example.com>"],
  "from": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "to": [
    { "name": "Support Team", "email": "support@yourdomain.com" }
  ],
  "cc": [],
  "bcc": [],
  "subject": "Support Request #1234",
  "body": {
    "text": "Hi, I'm having trouble with my account.",
    "html": "<p>Hi, I'm having trouble with my account.</p>"
  },
  "attachments": [
    {
      "id": "att_123",
      "filename": "screenshot.png",
      "contentType": "image/png",
      "size": 102456,
      "url": "/api/email/attachments/att_123"
    }
  ],
  "headers": {
    "X-Custom-Header": "value"
  },
  "isRead": false,
  "receivedAt": "2024-01-15T10:00:00Z"
}

Mark as Read/Unread

Update the read status of a message.

PATCH /api/email/inboxes/:inboxId/messages/:messageId

Request Body:

{
  "isRead": true
}

Get Raw Message

Retrieve the raw MIME content of a message.

GET /api/email/inboxes/:inboxId/messages/:messageId/raw

Response:

Content-Type: text/plain

From: john@example.com
To: support@yourdomain.com
Subject: Support Request #1234
Date: Mon, 15 Jan 2024 10:00:00 +0000
MIME-Version: 1.0

Hi, I'm having trouble with my account.

Code Examples

List Recent Threads

const response = await fetch(
  `/api/email/inboxes/${inboxId}/threads?limit=10&status=active`,
  {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  }
);

const { threads } = await response.json();

// Display thread summaries
threads.forEach(thread => {
  console.log(`${thread.subject} (${thread.unreadCount} unread)`);
});

Mark Thread as Read

await fetch(
  `/api/email/inboxes/${inboxId}/threads/${threadId}`,
  {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ isRead: true })
  }
);

Search Messages

const response = await fetch(
  `/api/email/inboxes/${inboxId}/threads?search=invoice&from=john@example.com`,
  {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  }
);

const results = await response.json();

Webhook Events

Thread and message events trigger webhooks:

Event	Description
`thread.created`	New thread received
`thread.updated`	Thread status changed
`message.received`	New message in thread
`message.read`	Message marked as read

Error Codes

Code	Description
`THREAD_NOT_FOUND`	Thread does not exist
`MESSAGE_NOT_FOUND`	Message does not exist
`INBOX_ACCESS_DENIED`	No access to this inbox
`INVALID_STATUS`	Invalid status value

Inboxes - Manage email inboxes
Webhooks - Real-time notifications
Sending Email - Send replies

Threads & Messages

On this page