Get message sync 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.
bearerAuthAuthorizationBearer <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: [].
mailboxId*stringMailbox ULID identifier
since?stringA previous newState. Omit to bootstrap: returns the current state and no changes.
length <= 200limit?integerMaximum ids per response across all three sets (default and cap 500)
1 <= value <= 500include?stringComma-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.
length <= 64The changes since since (or the current state, on a bootstrap call)
application/json- 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*booleanTrue if more changes remain to be polled immediately
labels?array<>With include=labels: the label vector as of newState, exactly GET /labels' shape
newState*stringNew opaque state token for the next sync poll
oldState?stringEcho 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
curl -X GET 'https://api.open.email/api/v1/mailboxes/string/messages/changes'{
"created": [],
"destroyed": [],
"hasMore": false,
"newState": "MjgtOTE4NDI",
"updated": []
}Messages similar to one message GET
'More like this': the message's own embedding is the query. The message must already be embedded (semantic search on, and the backfill has reached it)…
Subscribe to live mailbox change events over… GET
Upgrades to a WebSocket that streams best-effort change signals for this mailbox: message.new (delivery), message.updated / message.expunged / message.restored…