Skip to content
Extrovert Extrovert Docs

Mark a message read or unread

PATCH
/v1/inboxes/{inbox_id}/messages/{id}

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
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

Opaque message id (msg_...). Encodes its owning inbox.

Request Body required

Section titled “Request Body required ”
object
read

Set the native IMAP \Seen flag (true = read, false = unread).

boolean

Responses

Section titled “ Responses ”

200

Section titled “200 ”

The updated message.

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

Section titled “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

Section titled “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

Section titled “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