Skip to main content
POST
Read one message

Authorizations

Authorization
string
header
required

Bearer credential for one agent: an API key or an access token (a JWT). Pass as Authorization: Bearer <credential>.

A key is shown once when it is issued and is not recoverable afterwards; an access token lives five minutes and is fetched with the agent's own client key from the access service. Treat both as secrets: they reach one agent's mail, and anything a delegation has extended to it. An access token's scope is a ceiling on what the agent may do with it.

Body

application/json
id
string
required

The message, by its identifier. The identifier says which kind it is, so there is no second field to route on, and an identifier of the wrong kind is refused rather than guessed at.

Example:

"message_01j9x2v8k3e0080000000000"

render
enum<string>

text (the default) is the safe rendering. raw is the original message as it arrived. parts lists its structure, with the part numbers part.describe takes.

Available options:
text,
raw,
parts
max_chars
integer

Truncate the rendering. At most, and by default, 20000. A truncated response carries truncated and a cursor to continue from, rather than silently stopping. Ignored with render: raw.

cursor
string

Continue a truncated rendering.

quoted
boolean

Not served: quoted history stays folded, and asking for it is unavailable. Read with render: raw for the original.

Response

The object.

ref
string

What was read, as the server understood it.

kind
string

Which shape this is, so a client can branch without re-parsing.

text
string

The rendering, for the kinds that have one.

content
object

The structured form, for the kinds that have one. Its shape depends on kind.

provenance
object

Where the content came from. Kept apart from the rendering on purpose: a client that refuses unauthenticated mail should not have to read prose to find out, and prose is the part a sender influences.

cursor
string

Present when there is more to read.

truncated
boolean

There is more than this response carries.

error
object