Skip to Content
GET
/api/v1/mailboxes/{mailboxId}/messages/changes

Answers created / updated / destroyed message ids for everything that happened since since, plus a newState to send next time. Ids only: fetch what you need through the ordinary message endpoints.

The loop. Call once with no since to get a starting newState; do your full listing; then poll with since=<newState>, or better, subscribe to GET /mailboxes/{mailboxId}/events and call this whenever a frame arrives (a state.changed frame's Email value is itself a valid since). Keep calling while hasMore is true.

What maps to what. A delivery is created, and so is a restore from trash. Flag, keyword and label changes are updated, as is a message whose conversation was merged into another. An expunge (soft delete to trash) and a purge are both destroyed — this feed mirrors the ordinary live listing, so use ?state=expunged if you present a trash view. The feed errs toward telling you too much: a message may be reported created where updated would have done, which costs one refetch. It never reports a message you still hold as destroyed.

When the token is too old (or was minted by a mailbox that has since been rebuilt) you get 410 cannot_calculate_changes. There is no repair: re-list the mailbox and bootstrap a fresh token. History is kept for 30 days, comfortably longer than the 14-day trash window, so this only happens to a client that has been away a long time.

Authorization

bearerAuth
headerAuthorizationBearer <token>

Two credential kinds share this scheme; GET /api/v1/auth/whoami answers which one you hold and what it reaches.

oek_… API key (minted by POST /api/v1/api-keys; shown once at mint). role: account reaches the full account surface: the directory (domains, routes, patterns, api-keys, accounts, address lists) plus every mailbox the account owns. role: system additionally reaches the operator surface, which is documented separately.

oemp_… mailbox app password (minted by POST /api/v1/identities/{identityId}/credentials). Reaches ONE mailbox: its messages, labels, threads, search, sync, send, filters and PIM collections. Directory routes refuse it with 403 insufficient_scope.

Refusal vocabulary: a missing, malformed, expired, or revoked credential answers 401 unauthorized with a WWW-Authenticate: Bearer challenge; a VALID credential outside its scope answers 403 (insufficient_scope for an app password on a directory route, system_credentials_required where only the operator may call). The public routes (health, branding, token-in-path capabilities) declare security: [].

Path Parameters

mailboxId*string

Mailbox ULID identifier

Query Parameters

since?string

A previous newState. Omit to bootstrap: returns the current state and no changes.

Lengthlength <= 200
limit?integer

Maximum ids per response across all three sets (default and cap 500)

Range1 <= value <= 500
include?string

Comma-separated companions computed in the SAME store turn as the feed, so they describe exactly the state newState names: labels — the label vector GET /labels returns (counts, UIDVALIDITY, UIDNEXT, HIGHESTMODSEQ), sync — for every id in created and updated on this page, the folder-sync projection (per-label uid/modseq, flags, keywords, blobHash, size, receivedAt) under sync. A sync client that asks for both makes ONE request per poll instead of changes + labels + N × batch.

Lengthlength <= 64

Response Body

The changes since since (or the current state, on a bootstrap call)

application/json
  1. response
created*array<string>

Message IDs that newly appeared (delivered, imported, or restored)

destroyed*array<string>

Message IDs that were deleted, expunged, or purged

hasMore*boolean

True if more changes remain to be polled immediately

labels?array<>

With include=labels: the label vector as of newState, exactly GET /labels' shape

newState*string

New opaque state token for the next sync poll

oldState?string

Echo of the previous state token passed in the request

sync?

With include=sync: the folder-sync projection of every created/updated id on this page, keyed by id

updated*array<string>

Message IDs whose flags, keywords, labels, or thread changed

Example Request
curl -X GET 'https://api.open.email/api/v1/mailboxes/string/messages/changes'
Example Response
{
  "created": [],
  "destroyed": [],
  "hasMore": false,
  "newState": "MjgtOTE4NDI",
  "updated": []
}