# 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.

## `GET /api/v1/mailboxes/{mailboxId}/messages/changes`

### Path parameters

- `mailboxId` (string, required) — Mailbox ULID identifier

### Query parameters

- `since` (string, max 200 chars) — A previous `newState`. Omit to bootstrap: returns the current state and no changes.
- `limit` (integer, ≥ 1, ≤ 500) — Maximum ids per response across all three sets (default and cap 500)
- `include` (string, max 64 chars) — 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`.

### Responses

**200** — The changes since `since` (or the current state, on a bootstrap call)

`application/json` → MessageChangesFeed

- `created` (string[], required) — Message IDs that newly appeared (delivered, imported, or restored)
- `destroyed` (string[], required) — Message IDs that were deleted, expunged, or purged
- `hasMore` (boolean, required) — True if more changes remain to be polled immediately
- `newState` (string, required) — New opaque state token for the next sync poll
- `updated` (string[], required) — Message IDs whose flags, keywords, labels, or thread changed
- `labels` (LabelInfo[]) — With `include=labels`: the label vector as of `newState`, exactly `GET /labels`' shape
  - `bytes` (integer <int64>, required) — Total storage size of live messages in this label in bytes
  - `color` (string | null, required) — Hex color code (#rrggbb) or null
  - `deletedCount` (integer <int64>, required) — Number of live messages marked with \Deleted flag
  - `highestModseq` (integer <int64>, required) — Current RFC 7162 HIGHESTMODSEQ change tracker for this label
  - `id` (integer <int64>, required) — Internal label numeric ID
  - `isSubscribed` (boolean, required) — True if folder is subscribed for client synchronization
  - `messageCount` (integer <int64>, required) — Total number of live messages in this label
  - `name` (string, required) — Label or folder name (e.g. INBOX, Archive, custom name)
  - `role` ("inbox" | "sent" | "drafts" | "trash" | "archive" | "junk", required) — System role if special folder, or null for custom user labels
  - `sortOrder` (integer <int64>, required) — Display sort order index for mailbox list
  - `uidNext` (integer <int64>, required) — Next message UID that will be assigned in this label
  - `uidValidity` (integer <int64>, required) — IMAP UIDVALIDITY epoch for this label
  - `unseenCount` (integer <int64>, required) — Number of unread messages in this label
- `oldState` (string) — Echo of the previous state token passed in the request
- `sync` (object) — With `include=sync`: the folder-sync projection of every `created`/`updated` id on this page, keyed by id

**400** — validation_failed

`application/json` → ErrorOrValidation

**401** — unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge

`application/json` → ErrorBody

**404** — Mailbox not found or not accessible to this principal

`application/json` → ErrorBody

**410** — cannot_calculate_changes — the token is too old or foreign; re-list and bootstrap a new one

`application/json` → ErrorBody

**503** — temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)

`application/json` → ErrorBody

### Example request

```bash
curl -X GET 'https://api.open.email/api/v1/mailboxes/{mailboxId}/messages/changes' \
  -H 'Authorization: Bearer oek_…'
```

## TypeScript SDK

[`openemail.messages.getChanges`](/docs/sdks/typescript/messages/get-changes)

```ts
const messageChangesFeed = await openemail.messages.getChanges(mailboxId)
```
