Mail Threads

List Threads

curl -X GET "https://inbound.new/api/e2/mail/threads?limit=25&unread=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET `/api/e2/mail/threads`

List email threads (conversations) for your inbox with cursor-based pagination. This is the primary endpoint for building an inbox UI. What is a Thread? A thread groups related emails together based on the In-Reply-To and References headers, similar to how Gmail groups conversations. Each thread contains both inbound (received) and outbound (sent) messages. Use with /mail/threads/:id: Use this endpoint to list threads, then use GET /mail/threads/:id to fetch all messages in a specific thread.

Query Parameters

limit

integer

default:"25"

Maximum number of threads to return (1-100).

cursor

string

Cursor for pagination. Pass the thread ID from pagination.next_cursor of the previous response to get the next page.

string

Search query to filter threads by subject or participant emails. Case-insensitive partial match.

unread

string

default:"false"

Filter by unread status. Set to true to only return threads with unread messages.

domain

string

Filter threads by domain. Accepts domain ID (e.g., dom_xxx) or domain name (e.g., example.com).Returns threads where any participant email matches the domain.

address

string

Filter threads by email address. Accepts address ID (e.g., addr_xxx) or raw email address.Returns threads where the address is a participant.

Response

threads

array

Array of thread objects matching the query, sorted by last message date (newest first).

Show Thread Object

string

Unique identifier for the thread.

root_message_id

string

RFC 2822 Message-ID of the first message in the thread.

normalized_subject

string

Normalized subject line (stripped of Re:, Fwd:, etc.) used for thread grouping.

participant_emails

string[]

Array of all unique email addresses that have participated in this thread.

participant_names

string[]

Array of formatted participant names in the format First Last <[email protected]> or just [email protected] if no name is available.

message_count

number

Total number of messages in the thread (both inbound and outbound).

last_message_at

string

ISO 8601 timestamp of the most recent message in the thread.

created_at

string

ISO 8601 timestamp when the thread was created (first message received).

latest_message

object

Preview of the most recent message in the thread.

Show Latest Message Object

string

Unique identifier of the message.

type

string

Message type: inbound or outbound.

subject

string

Subject line of the message.

from_text

string

Formatted sender information (name and/or email).

text_preview

string

First 200 characters of the message body.

is_read

boolean

Whether the message has been read (always true for outbound).

has_attachments

boolean

Whether the message has any attachments.

date

string

ISO 8601 timestamp of when the message was sent/received.

has_unread

boolean

Whether the thread has any unread inbound messages.

is_archived

boolean

Whether the thread has been archived.

unread_count

number

Number of unread messages in the thread.

pagination

object

Pagination metadata for cursor-based pagination.

Show Pagination Object

filters

object

Applied filters for this query.

Show Filters Object

string

Applied search query.

unread_only

boolean

Whether filtering for unread threads only.

domain

string

Applied domain filter (resolved domain name).

address

string

Applied address filter (resolved email address).

{
  "threads": [
    {
      "id": "thread_abc123",
      "root_message_id": "<[email protected]>",
      "normalized_subject": "project update",
      "participant_emails": [
        "[email protected]",
        "[email protected]",
        "[email protected]"
      ],
      "participant_names": [
        "Alice Johnson <[email protected]>",
        "[email protected]",
        "Bob Smith <[email protected]>"
      ],
      "message_count": 5,
      "last_message_at": "2024-01-15T14:30:00Z",
      "created_at": "2024-01-15T10:00:00Z",
      "latest_message": {
        "id": "eml_xyz789",
        "type": "inbound",
        "subject": "Re: Project update",
        "from_text": "Alice Johnson <[email protected]>",
        "text_preview": "Thanks for the update! I have a few questions about the timeline...",
        "is_read": false,
        "has_attachments": true,
        "date": "2024-01-15T14:30:00Z"
      },
      "has_unread": true,
      "is_archived": false,
      "unread_count": 2
    }
  ],
  "pagination": {
    "limit": 25,
    "has_more": true,
    "next_cursor": "thread_abc123"
  },
  "filters": {
    "unread_only": true
  }
}

Get Thread

curl -X GET https://inbound.new/api/e2/mail/threads/thread_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

GET `/api/e2/mail/threads/:id`

Retrieve a complete email thread (conversation) with all messages. What You Get:

Thread metadata (subject, participants, timestamps)
All messages in the thread (both inbound and outbound)
Messages sorted chronologically by thread position

Message Types:

inbound - Emails you received
outbound - Emails you sent (includes delivery status)

Response

thread

object

Thread metadata.

Show Thread Details

string

Unique identifier for the thread.

root_message_id

string

RFC 2822 Message-ID of the first message in the thread.

normalized_subject

string

Normalized subject line (stripped of Re:, Fwd:, etc.).

participant_emails

string[]

Array of all unique email addresses that have participated in this thread.

participant_names

string[]

Array of formatted participant names.

message_count

number

Total number of messages in the thread.

last_message_at

string

ISO 8601 timestamp of the most recent message.

created_at

string

ISO 8601 timestamp when the thread was created.

updated_at

string

ISO 8601 timestamp when the thread was last updated.

messages

array

Array of all messages in the thread, sorted by thread position (chronological).

Show Message Object

string

Unique identifier for the message.

message_id

string

RFC 2822 Message-ID header value.

type

string

Message type: inbound or outbound.

thread_position

number

Position of the message in the thread (0 = first message).

subject

string

Subject line of the message.

text_body

string

Plain text body of the message.

html_body

string

HTML body of the message.

from

string

Formatted sender (display name and email).

from_name

string

Sender display name if available.

from_address

string

Sender email address.

string[]

Array of recipient email addresses.

string[]

Array of CC recipient email addresses.

bcc

string[]

Array of BCC recipient email addresses.

date

string

ISO 8601 timestamp from the Date header.

received_at

string

ISO 8601 timestamp when the message was received (inbound only).

sent_at

string

ISO 8601 timestamp when the message was sent (outbound only).

is_read

boolean

Whether the message has been read (always true for outbound).

read_at

string

ISO 8601 timestamp when the message was marked as read.

has_attachments

boolean

Whether the message has any attachments.

attachments

array

Array of attachment metadata objects.

Show Attachment Object

filename

string

Original filename of the attachment.

contentType

string

MIME type of the attachment.

size

number

Size of the attachment in bytes.

contentId

string

Content-ID for inline attachments.

in_reply_to

string

RFC 2822 In-Reply-To header value.

references

string[]

Array of Message-IDs from the References header.

headers

object

Raw email headers as key-value pairs.

tags

array

Array of tags attached to the message (outbound only).

status

string

Delivery status for outbound messages: pending, sent, failed, or bounced.

failure_reason

string

Error message if the outbound message failed to send.

total_count

number

Total number of messages returned.

{
  "thread": {
    "id": "thread_abc123",
    "root_message_id": "<[email protected]>",
    "normalized_subject": "project update",
    "participant_emails": [
      "[email protected]",
      "[email protected]"
    ],
    "participant_names": [
      "Alice Johnson <[email protected]>",
      "[email protected]"
    ],
    "message_count": 3,
    "last_message_at": "2024-01-15T14:30:00Z",
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T14:30:00Z"
  },
  "messages": [
    {
      "id": "eml_first123",
      "message_id": "<[email protected]>",
      "type": "inbound",
      "thread_position": 0,
      "subject": "Project update",
      "text_body": "Here's the latest update on the project...",
      "html_body": "<p>Here's the latest update on the project...</p>",
      "from": "Alice Johnson <[email protected]>",
      "from_name": "Alice Johnson",
      "from_address": "[email protected]",
      "to": ["[email protected]"],
      "cc": [],
      "bcc": [],
      "date": "2024-01-15T10:00:00Z",
      "received_at": "2024-01-15T10:00:01Z",
      "sent_at": null,
      "is_read": true,
      "read_at": "2024-01-15T10:05:00Z",
      "has_attachments": false,
      "attachments": [],
      "in_reply_to": null,
      "references": [],
      "headers": {},
      "tags": []
    },
    {
      "id": "eml_reply456",
      "message_id": "<[email protected]>",
      "type": "outbound",
      "thread_position": 1,
      "subject": "Re: Project update",
      "text_body": "Thanks for the update! Here are my thoughts...",
      "html_body": "<p>Thanks for the update! Here are my thoughts...</p>",
      "from": "[email protected]",
      "from_name": null,
      "from_address": "[email protected]",
      "to": ["[email protected]"],
      "cc": [],
      "bcc": [],
      "date": "2024-01-15T12:00:00Z",
      "received_at": null,
      "sent_at": "2024-01-15T12:00:00Z",
      "is_read": true,
      "read_at": "2024-01-15T12:00:00Z",
      "has_attachments": false,
      "attachments": [],
      "in_reply_to": "<[email protected]>",
      "references": ["<[email protected]>"],
      "headers": {
        "In-Reply-To": "<[email protected]>",
        "References": "<[email protected]>"
      },
      "tags": [],
      "status": "sent",
      "failure_reason": null
    },
    {
      "id": "eml_reply789",
      "message_id": "<[email protected]>",
      "type": "inbound",
      "thread_position": 2,
      "subject": "Re: Project update",
      "text_body": "Great points! I have a few questions...",
      "html_body": "<p>Great points! I have a few questions...</p>",
      "from": "Alice Johnson <[email protected]>",
      "from_name": "Alice Johnson",
      "from_address": "[email protected]",
      "to": ["[email protected]"],
      "cc": [],
      "bcc": [],
      "date": "2024-01-15T14:30:00Z",
      "received_at": "2024-01-15T14:30:01Z",
      "sent_at": null,
      "is_read": false,
      "read_at": null,
      "has_attachments": true,
      "attachments": [
        {
          "filename": "questions.pdf",
          "contentType": "application/pdf",
          "size": 125678,
          "contentId": null
        }
      ],
      "in_reply_to": "<[email protected]>",
      "references": [
        "<[email protected]>",
        "<[email protected]>"
      ],
      "headers": {},
      "tags": []
    }
  ],
  "total_count": 3
}

Threading Logic

Email threads are created automatically based on standard email headers:

Thread Grouping Rules

In-Reply-To Header: Links a message to its parent
References Header: Contains the full chain of Message-IDs
Normalized Subject: Fallback grouping by subject (with Re:, Fwd: stripped)

Example Thread Structure

Thread: "Project Update"
├─ Message 1 (Inbound) - "Project update"
│  Message-ID: <[email protected]>
│
├─ Message 2 (Outbound) - "Re: Project update"
│  In-Reply-To: <[email protected]>
│  References: <[email protected]>
│
└─ Message 3 (Inbound) - "Re: Project update"
   In-Reply-To: <[email protected]>
   References: <[email protected]> <[email protected]>

Building an Inbox UI

Step 1: List Threads

Use /mail/threads to display a thread list (like Gmail’s inbox):

const { threads, pagination } = await inbound.mail.threads.list({
  limit: 25,
  unread: true
})

// Display threads
for (const thread of threads) {
  console.log(`[${thread.has_unread ? '●' : ' '}] ${thread.normalized_subject}`)
  console.log(`   ${thread.participant_names.join(', ')}`)
  console.log(`   ${thread.latest_message.text_preview}`)
  console.log(`   ${thread.message_count} messages, ${thread.unread_count} unread`)
  console.log()
}

Step 2: Display Thread

When user clicks a thread, use /mail/threads/:id to show all messages:

const { thread, messages } = await inbound.mail.threads.get('thread_abc123')

// Display conversation
console.log(`Thread: ${thread.normalized_subject}`)
console.log(`Participants: ${thread.participant_names.join(', ')}`)
console.log()

for (const message of messages) {
  console.log(`[${message.type === 'inbound' ? '→' : '←'}] ${message.from}`)
  console.log(`   ${message.subject}`)
  console.log(`   ${message.text_body}`)
  console.log()
}

Step 3: Reply to Thread

Use /emails/:id/reply to reply within the thread:

// Reply to the thread (uses thread ID)
const reply = await inbound.emails.reply('thread_abc123', {
  from: '[email protected]',
  text: 'Thanks for your questions!',
  html: '<p>Thanks for your questions!</p>'
})

Overview

Endpoints

List Threads

GET `/api/e2/mail/threads`

Query Parameters

Response

Get Thread

GET `/api/e2/mail/threads/:id`

Response

Threading Logic

Thread Grouping Rules

Example Thread Structure

Building an Inbox UI

Step 1: List Threads

Step 2: Display Thread

Step 3: Reply to Thread

Build docs developers (and LLMs) love

Overview

Endpoints

​List Threads

​GET /api/e2/mail/threads

​Query Parameters

​Response

​Get Thread

​GET /api/e2/mail/threads/:id

​Response

​Threading Logic

​Thread Grouping Rules

​Example Thread Structure

​Building an Inbox UI

​Step 1: List Threads

​Step 2: Display Thread

​Step 3: Reply to Thread

Build docs developers (and LLMs) love

List Threads

GET `/api/e2/mail/threads`

Query Parameters

Response

Get Thread

GET `/api/e2/mail/threads/:id`

Response

Threading Logic

Thread Grouping Rules

Example Thread Structure

Building an Inbox UI

Step 1: List Threads

Step 2: Display Thread

Step 3: Reply to Thread