Skip to main content
GET
cURL

Authorizations

Authorization
string
header
required

JWT Bearer token obtained from authentication. Pass as: Authorization: Bearer

Path Parameters

id
string
required

Unique email message identifier

Pattern: ^[cC][^\s-]{8,}$

Response

200 - application/json

OK

Full message resource representation

id
string
required

Unique identifier of the message

Pattern: ^[cC][^\s-]{8,}$
agentId
string
required

ID of the agent that sent or received the message

Pattern: ^[cC][^\s-]{8,}$
inboxId
string | null
required

ID of the inbox this message belongs to — the inbox it was delivered to (inbound) or sent from (outbound). Null when no inbox backs the address: SMS/MMS/voice messages, and email sent from an email identity that has no inbox (such as a custom-domain identity added to an agent). Pass it to GET /messages?inboxId= to list one inbox's mail.

Pattern: ^[cC][^\s-]{8,}$
channel
enum<string>
required

Communication channel used

Available options:
EMAIL,
SMS,
MMS,
VOICE
direction
enum<string>
required

Whether the message was inbound or outbound

Available options:
INBOUND,
OUTBOUND
status
enum<string>
required

Current delivery status

Available options:
QUEUED,
SENT,
DELIVERED,
FAILED,
BOUNCED,
BLOCKED,
PENDING_APPROVAL
fromAddress
string
required

Sender address (email or phone number)

toAddress
string
required

Recipient address (email or phone number)

subject
string | null
required

Message subject line, or null for channels that do not support subjects

body
string
required

Plain-text content of the message

bodyHtml
string | null
required

HTML content of the message, or null if not available

extractedText
string | null
required

Plain-text body with the quoted reply chain and signature stripped — just what this sender actually wrote. Read this instead of body to avoid re-reading (and paying for) the whole thread on every message. Null when nothing was extracted: non-email channels, messages your agent sent, and mail received before this field existed — so extractedText ?? body is always correct. Best-effort and heuristic; body remains the verbatim source of truth. Known weak cases: forwards and bottom-posted replies have no separable 'new' part, so this returns the full body rather than nothing.

extractedHtml
string | null
required

HTML body with quoted reply chains removed. Same semantics as extractedText; bodyHtml stays verbatim. Quoting styles that mark the chain with a sibling element rather than wrapping it (Outlook) are not stripped here — extractedText still is.

headers
object | null
required

Raw message headers as key-value pairs, or null

metadata
object | null
required

Arbitrary metadata attached to the message, or null

threadId
string | null
required

Thread identifier for conversation grouping, or null

labels
string[]
required

Workflow labels on this message. Always contains exactly one of the system labels unread or read; may also contain archived, spam (the inbound spam verdict — see includeSpam on list/search), and any labels you add yourself. Stored lowercase, deduped, and sorted. Change them with PATCH /messages/{id}/labels.

inReplyTo
string | null
required

Message ID this message is replying to, or null

externalId
string | null
required

External identifier, or null. For email: the RFC 5322 Message-ID (bare, no angle brackets) — pass it as inReplyTo to reply in-thread. For SMS: the provider-assigned message id.

deletedAt
string<date-time> | null
required

When this message was moved to Trash, or null if it is live. Deleted messages are hidden from listings unless deleted is set to include or only, and can be brought back with POST /messages/{id}/restore. Nothing purges them.

sentAt
string<date-time> | null
required

Timestamp when the message was sent, or null if not yet sent

receivedAt
string<date-time> | null
required

Timestamp when the message was received, or null for outbound messages

attachments
object[]
required

File attachments associated with this message

createdAt
string<date-time>
required

Timestamp when the message record was created

updatedAt
string<date-time>
required

Timestamp when the message record was last updated