Skip to main content
POST
Free and busy over a window

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

What to list within, a mailbox, a calendar, an addressbook.

Example:

"ag_01j9x2v8k3e0080000000000"

folder
string

Which folder.

Example:

"inbox"

unread
boolean

Only unread messages.

agent
boolean

Only messages carrying a machine-readable part.

since
string<date-time>
before
string<date-time>
from
string

Restrict to one sender.

thread
string

Restrict to one conversation.

q
string

Look up by address, for contacts.

limit
integer

How many to return.

cursor
string

Resume a listing.

max_chars
integer

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