Get one persistent thread and its messages

GET

/v1/admin/orgs/{org_id}/projects/{project_id}/inboxes/{addr}/threads/{thread_id}

• Production
• Local

Authorizations

• ClerkSession
• AgentKey
  account:admin

Parameters

Path Parameters

org_id

required

string

project_id

required

string

addr

required

string

The full inbox address, URL-encoded (e.g. agent7%40extrovertmail.com).

thread_id

required

string

Responses

200

Thread messages, oldest-first.

object

last_message_direction

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

string

Allowed values: inbound outbound

message_count

integer

last_message_id

string

last_message_at

string

participants

Array<string>

unread

boolean

snippet

string

thread_id

string

subject

string

messages

Array<object>

A source-preserving message shape for the console plane.

object

submission_id

string

sent_message_id

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

string

seq

string

thread_id

string

direction

string

Allowed values: inbound outbound

from

string

to

string

cc

string

bcc

Bcc recorded on the owning sender’s Sent copy only; absent when not recorded or not authorized. Never part of participant summaries.

string

reply_to

string

subject

string

date

string

message_id

string

in_reply_to

string

references

string

seen

boolean

has_attachments

boolean

body

string

text

string

html

string

extracted_text

string

extracted_html

string

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