Get one thread with its messages

GET

/v1/projects/{project_id}/inboxes/{inbox_id}/threads/{id}

• Production
• Local

Authorizations

• AgentKey
  mailbox:read

Parameters

Path Parameters

project_id

required

string

Project containing the authorized inbox.

inbox_id

required

string

Opaque inbox id (the canonical path key). The inbox’s email address is also accepted here as a within-project alias. Treat the id as opaque.

id

required

string

Thread id.

Responses

200

The thread and its messages (oldest-first).

object

id

string

Example

thr_9aB

inbox_id

string

Example

agent7@extrovertmail.com

subject

string

participants

Array<string>

message_count

integer

last_message_at

string

snippet

string

unread

Whether the latest message is unread.

boolean

last_message_id

Opaque id of the latest message; usable by message endpoints.

string

last_message_direction

Direction of the actual latest message relative to the owning inbox. Omitted when unavailable.

string

Allowed values: inbound outbound

last_message_has_attachments

Whether the latest message has attachments.

boolean

context_version

Opaque snapshot of available conversation content. Read the complete context before composing and pass this as expected_context_version when replying or revising; a changed snapshot requires rereading.

string

messages

The thread’s messages, oldest-first.

Array<object>

The canonical message wire shape (agent plane).

object

submission_id

Opaque status handle for a tracked outbound submission.

string

sent_message_id

Resolvable msg_ selector when the Sent copy is available.

string

nullable

sent_copy_status

Whether the accepted message has a resolvable saved Sent copy. Archive failure never resends mail.

string

Allowed values: pending stored unavailable

transport

Per-recipient counts by transport state. Absent states have count zero.

object

queued

integer

waiting_for_parent

integer

transmitting

integer

accepted

integer

failed

integer

dependency_failed

integer

unknown

integer

id

Opaque

string

Example

msg_8Tz

thread_id

string

Example

thr_9aB

inbox

string

Example

agent7@extrovertmail.com

direction

Derived relative to the owning inbox.

string

Allowed values: inbound outbound

from

A structured RFC5322 address.

object

name

string

Example

Acme Support

email

required

string format: email

Example

support@acme.test

to

Array<object>

A structured RFC5322 address.

object

name

string

Example

Acme Support

email

required

string format: email

Example

support@acme.test

cc

Array<object>

A structured RFC5322 address.

object

name

string

Example

Acme Support

email

required

string format: email

Example

support@acme.test

bcc

Explicit Bcc retained on the sender’s Sent copy only. Empty when unavailable; never inferred for inbound mail or older copies.

Array<object>

A structured RFC5322 address.

object

name

string

Example

Acme Support

email

required

string format: email

Example

support@acme.test

reply_to

Array<object>

A structured RFC5322 address.

object

name

string

Example

Acme Support

email

required

string format: email

Example

support@acme.test

subject

string

text

Decoded UTF-8 text/plain MIME alternative; null when the message had no plain-text part. Never derived from HTML.

string

nullable

html

Decoded text/html MIME alternative; null for text-only mail. Never synthesized from plain text.

string

nullable

extracted_text

Best-effort derivative of text with quoted history and signatures removed; null when text is absent or no authored text remains. Not authoritative.

string

nullable

extracted_html

Best-effort derivative of html with common quoted-history containers removed; null when html is absent or no authored HTML remains. Not authoritative.

string

nullable

date

Original Date header value.

string

message_id

RFC5322 Message-ID.

string

in_reply_to

RFC5322 In-Reply-To header.

string

references

RFC5322 References header chain.

string

folder

string

seen

Native IMAP \Seen flag (read state).

boolean

400

Invalid request.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean

401

Missing or invalid credential.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean

404

Resource not found.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean

413

Thread exceeds the 1,000-message or 12 MiB combined-source detail limit; no complete context snapshot is returned.