Skip to main content
POST
Read one part of a message

Authorizations

Authorization
string
header
required

Bearer token for one agent. Pass as Authorization: Bearer <token>.

A token is shown once when it is issued and is not recoverable afterwards. Treat it as a secret: it reaches one agent's mail, calendar and contacts, and anything a grant has extended to it.

Body

application/json
id
string
required

The object, 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"

part
string

For a message, which part to read.

uid
string

For a calendar, which event.

contact
string

For an addressbook, which contact.

render
string

How to render the content.

max_chars
integer

Truncate the rendering. A truncated response says how to continue rather than silently stopping.

cursor
string

Continue a truncated rendering.

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 and what was removed from it. 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.

error
object