# messages.getChanges

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.

```ts
openemail.messages.getChanges(
  mailboxId: string,
  options?: MessagesGetChangesOptions,
): ApiPromise<MessageChangesFeed>
```

It calls `GET /mailboxes/{mailboxId}/messages/changes`: [Get message sync changes](/docs/api/messages/get_MessageChanges) in the API reference.

## Example

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

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `mailboxId` | `string` | Mailbox ULID identifier. The path's `{mailboxId}`. |

## Options

The last argument, `options`, a `MessagesGetChangesOptions`, takes:

| Option | Type | Sent as | Description |
| --- | --- | --- | --- |
| `since` | `string` | query `since` | A previous `newState`. Omit to bootstrap: returns the current state and no changes. |
| `limit` | `number` | query `limit` | Maximum ids per response across all three sets (default and cap 500) |
| `include` | `string` | query `include` | 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`. |

Every call also takes `signal`, `timeout`, `retry` and `headers`, which say how that one call is sent ([call options](/docs/sdks/typescript/calling-methods#call-options)).

## Answer

Awaited, it is the API's JSON, [`MessageChangesFeed`](/docs/sdks/typescript/types/message-changes-feed). It is an [`ApiPromise`](/docs/sdks/typescript/responses): `.withResponse()` gives the same with the `Response` it came in, for its headers.

## Errors

| Status | What it means |
| --- | --- |
| `400` | validation_failed |
| `401` | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge |
| `404` | Mailbox not found or not accessible to this principal |
| `410` | cannot_calculate_changes — the token is too old or foreign; re-list and bootstrap a new one |
| `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) |

A failed call rejects with a [`RequestError`](/docs/sdks/typescript/errors): its `status`, and its `code`, the API's `error`. Decide on the code: one status covers several.

## Types

It names these types of the API, each on a page of its own: [`MessageChangesFeed`](/docs/sdks/typescript/types/message-changes-feed).
