Skip to Content
GET
/api/v1/mailboxes/{mailboxId}/threads/{threadId}

Returns all messages in a conversation thread in chronological order, with pre-computed reply context (In-Reply-To, References, suggested subject and recipient). Automatically resolves merged threads.

Authorization

bearerAuth
headerAuthorizationBearer <token>

Two credential kinds share this scheme; GET /api/v1/auth/whoami answers which one you hold and what it reaches.

oek_… API key (minted by POST /api/v1/api-keys; shown once at mint). role: account reaches the full account surface: the directory (domains, routes, patterns, api-keys, accounts, address lists) plus every mailbox the account owns. role: system additionally reaches the operator surface, which is documented separately.

oemp_… mailbox app password (minted by POST /api/v1/identities/{identityId}/credentials). Reaches ONE mailbox: its messages, labels, threads, search, sync, send, filters and PIM collections. Directory routes refuse it with 403 insufficient_scope.

Refusal vocabulary: a missing, malformed, expired, or revoked credential answers 401 unauthorized with a WWW-Authenticate: Bearer challenge; a VALID credential outside its scope answers 403 (insufficient_scope for an app password on a directory route, system_credentials_required where only the operator may call). The public routes (health, branding, token-in-path capabilities) declare security: [].

Path Parameters

mailboxId*string

Mailbox ULID identifier

threadId*string

Conversation thread identifier

Query Parameters

cursor?string

Pagination cursor for next page of messages within thread

limit?integer

Maximum messages to return per page (max 200)

Range1 <= value <= 200
label?string

Folder context for the hidden-role filter — same label the listing was filtered by. Without it, and in every folder but Trash and Junk, members carrying the Trash or Junk label are excluded from both messages and messageCount; pass the Trash label to see exactly the trashed members, or the Junk label for the junked ones (a member in both is in Trash, not in Junk). This is the member set PATCH /messages's threadIds expands to, so a client that renders this view is acting on what it rendered.

Response Body

Conversation thread details and message history

application/json
  1. response
canonicalThreadId?string

Canonical thread ID if requested ID was merged

messageCount*integer

Total count of messages in this conversation

Formatint64
messages*array<>

List of messages in this thread in chronological order

nextCursor?string

Pagination cursor for next page of messages

replyContext*|

Pre-computed context for replying to this thread

threadId*string

Canonical conversation thread identifier (ULID)

Example Request
curl -X GET 'https://api.open.email/api/v1/mailboxes/string/threads/string'
Example Response
{
  "canonicalThreadId": "string",
  "messageCount": 0,
  "messages": [
    {
      "auth": {
        "arc": "string",
        "dkim": "string",
        "dmarc": "string",
        "junk": true,
        "spf": "string"
      },
      "bcc": [
        {
          "email": "string",
          "name": "string"
        }
      ],
      "blobGen": "string",
      "blobHash": "string",
      "cc": [
        {
          "email": "string",
          "name": "string"
        }
      ],
      "deliveryMeta": {
        "property1": null,
        "property2": null
      },
      "deliveryState": "queued",
      "envelopeFrom": "string",
      "envelopeTo": "string",
      "flags": [
        "string"
      ],
      "from": [
        {
          "email": "string",
          "name": "string"
        }
      ],
      "hasAttachment": true,
      "id": "string",
      "inReplyTo": "string",
      "keywords": [
        "string"
      ],
      "labels": [
        {
          "deleted": true,
          "modseq": 0,
          "name": "string",
          "uid": 0,
          "uidValidity": 0
        }
      ],
      "messageIdHeader": "string",
      "modseq": 0,
      "receivedAt": 0,
      "referencesIds": [
        "string"
      ],
      "restoresTo": [
        "string"
      ],
      "sentAt": 0,
      "size": 0,
      "snippet": "string",
      "subject": "string",
      "threadId": "string",
      "to": [
        {
          "email": "string",
          "name": "string"
        }
      ],
      "uid": 0
    }
  ],
  "nextCursor": "string",
  "replyContext": {
    "from": "string",
    "inReplyTo": "string",
    "inboundSourceId": "string",
    "references": [
      "string"
    ],
    "subject": "string",
    "to": "string"
  },
  "threadId": "string"
}