Threads

Threads group related messages into conversations. They are created automatically when messages are sent or received — you cannot create a thread directly. Threads are ordered by most recent activity.

List threads

GET /mailboxes/{email_address}/threads

List threads for a mailbox with cursor pagination, ordered by most recent message activity.

Path parameters

Parameter	Type	Description
`email_address`	string	Email address of the mailbox

Query parameters

Parameter	Type	Default	Description
`cursor`	string	—	Opaque cursor from a previous response’s `next_cursor`
`limit`	integer	50	Results per page (1–100)
`folder`	string	All accessible folders	Filter by `inbox`, `spam`, `archive`, or `blocked`. Viewing blocked threads requires an admin API key or the Inkbox Console.

Response (200)

JSON

{
  "items": [
    {
      "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "mailbox_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "subject": "Your order is confirmed",
      "folder": "inbox",
      "message_count": 3,
      "last_message_at": "2025-03-02T09:15:00Z",
      "created_at": "2025-03-01T12:00:00Z"
    }
  ],
  "next_cursor": "eyJ0cyI6ICIyMDI1LTAzLTAxVDEyOjAwOjAwWiIsICJpZCI6ICJkNGU1ZjZhNyJ9",
  "has_more": false
}

Code examples

curl -X GET "https://inkbox.ai/api/v1/mail/mailboxes/EMAIL_ADDRESS/threads?limit=25" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch(
  `https://inkbox.ai/api/v1/mail/mailboxes/${emailAddress}/threads?limit=25`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const page = await response.json();

import requests

response = requests.get(
    f"https://inkbox.ai/api/v1/mail/mailboxes/{email_address}/threads",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"limit": 25},
)
page = response.json()

Get thread

GET /mailboxes/{email_address}/threads/{thread_id}

Get a single thread with all its messages (metadata only — no body content) inline.

Path parameters

Parameter	Type	Description
`email_address`	string	Email address of the mailbox
`thread_id`	UUID	Unique identifier of the thread

Response (200)

JSON

{
  "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "mailbox_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "subject": "Your order is confirmed",
  "folder": "inbox",
  "message_count": 2,
  "last_message_at": "2025-03-02T09:15:00Z",
  "created_at": "2025-03-01T12:00:00Z",
  "messages": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "mailbox_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "thread_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "message_id": "<20250301120000.abc123@inkboxmail.com>",
      "from_address": "agent-sales@inkboxmail.com",
      "to_addresses": ["customer@example.com"],
      "cc_addresses": null,
      "subject": "Your order is confirmed",
      "snippet": "Hi! Your order #1234 has been confirmed...",
      "direction": "outbound",
      "status": "sent",
      "is_read": true,
      "is_starred": false,
      "has_attachments": false,
      "created_at": "2025-03-01T12:00:00Z"
    },
    {
      "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
      "mailbox_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "thread_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "message_id": "<20250302091500.def456@example.com>",
      "from_address": "customer@example.com",
      "to_addresses": ["agent-sales@inkboxmail.com"],
      "cc_addresses": null,
      "subject": "Re: Your order is confirmed",
      "snippet": "Thanks! When will it arrive?",
      "direction": "inbound",
      "status": "received",
      "is_read": false,
      "is_starred": false,
      "has_attachments": false,
      "created_at": "2025-03-02T09:15:00Z"
    }
  ]
}

Code examples

curl -X GET "https://inkbox.ai/api/v1/mail/mailboxes/EMAIL_ADDRESS/threads/THREAD_ID" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch(
  `https://inkbox.ai/api/v1/mail/mailboxes/${emailAddress}/threads/${threadId}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const thread = await response.json();

import requests

response = requests.get(
    f"https://inkbox.ai/api/v1/mail/mailboxes/{email_address}/threads/{thread_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
thread = response.json()

List populated folders

GET /mailboxes/{email_address}/threads/folders

List the folders containing at least one accessible thread in the mailbox. Returns a sorted JSON array of folder names. Empty folders are omitted.

JSON

["archive", "inbox"]

cURL

curl "https://inkbox.ai/api/v1/mail/mailboxes/EMAIL_ADDRESS/threads/folders" \
  -H "X-API-Key: YOUR_API_KEY"

Move a thread

PATCH /mailboxes/{email_address}/threads/{thread_id}

Move a thread to inbox, spam, or archive. Use a claimed agent API key for its own mailbox, or an admin API key. Omitting folder or passing null leaves the folder unchanged. You cannot set folder to blocked. Returns the updated ThreadResponse with 200 OK. An unsupported folder returns 422. A missing thread returns 404; insufficient access can return 403 or 404.

cURL

curl -X PATCH "https://inkbox.ai/api/v1/mail/mailboxes/EMAIL_ADDRESS/threads/THREAD_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"folder": "archive"}'

Delete thread

DELETE /mailboxes/{email_address}/threads/{thread_id}

Delete a thread. Returns 204 No Content on success. Deleting a thread deletes the messages in it and frees their storage immediately — those bytes stop counting toward the inbox’s storage cap right away.

Path parameters

Parameter	Type	Description
`email_address`	string	Email address of the mailbox
`thread_id`	UUID	Unique identifier of the thread

Code examples

curl -X DELETE "https://inkbox.ai/api/v1/mail/mailboxes/EMAIL_ADDRESS/threads/THREAD_ID" \
  -H "X-API-Key: YOUR_API_KEY"

await fetch(
  `https://inkbox.ai/api/v1/mail/mailboxes/${emailAddress}/threads/${threadId}`,
  {
      method: "DELETE",
      headers: { "X-API-Key": "YOUR_API_KEY" },
  }
);

import requests

requests.delete(
    f"https://inkbox.ai/api/v1/mail/mailboxes/{email_address}/threads/{thread_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
)

Thread object

ThreadResponse (list items)

Field	Type	Description
`id`	UUID	Unique thread identifier
`mailbox_id`	UUID	Owning mailbox
`subject`	string \| null	Subject from the first message in the thread
`folder`	string	`inbox`, `spam`, `archive`, or `blocked`
`message_count`	integer	Number of messages in the thread
`last_message_at`	string	Timestamp of the most recent message (ISO 8601)
`created_at`	string	Thread creation timestamp (ISO 8601)

ThreadDetailResponse (single thread)

Includes all ThreadResponse fields plus:

Field	Type	Description
`messages`	MessageResponse[]	All active messages in the thread (metadata only, no body content)

Agent signup API

Agent identity API

Agent2Agent API

Mail API

Phone API

iMessage API

Webhooks API

Tunnels API

Contacts API

Notes API

Vault API

Billing API

List threads

Path parameters

Query parameters

Response (200)

Code examples

Get thread

Path parameters

Response (200)

Code examples

List populated folders

Move a thread

Delete thread

Path parameters

Code examples

Thread object

ThreadResponse (list items)

ThreadDetailResponse (single thread)

​List threads

​Path parameters

​Query parameters

​Response (200)

​Code examples

​Get thread

​Path parameters

​Response (200)

​Code examples

​List populated folders

​Move a thread

​Delete thread

​Path parameters

​Code examples

​Thread object

​ThreadResponse (list items)

​ThreadDetailResponse (single thread)

List threads

Path parameters

Query parameters

Response (200)

Code examples

Get thread

Path parameters

Response (200)

Code examples

List populated folders

Move a thread

Delete thread

Path parameters

Code examples

Thread object

ThreadResponse (list items)

ThreadDetailResponse (single thread)