Skip to main content
POST
List correspondents

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
in
string
required

The mailbox, by its agent's identifier.

Example:

"ag_01j9x2v8k3e0080000000000"

q
string

Only addresses containing this text, ignoring case.

limit
integer

How many correspondents to examine for this page. Default 50, at most 200. With q, a page can come back short or empty and still carry a cursor: keep paging until there is none.

cursor
string

Resume a listing, from the cursor the last page returned.

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