# identities.update

Update mailbox settings.

Updates mailbox storage quota, primary address label, and outbound sending limits; or, alone in its request, suspends or resumes the mailbox (`suspended`), or pauses, stops or restores its receiving (`receiveHold`). A control answers 200 once enforced everywhere core must enforce it, or 202 (with Retry-After) while that is still being applied: poll GET until suspensionPending, or receiveHoldPending, is false.

```ts
openemail.identities.update(
  identityId: string,
  body?: IdentitiesUpdateBody,
  options?: IdentitiesUpdateOptions,
): ApiPromise<Mailbox>
```

It calls `PATCH /identities/{identityId}`: [Update mailbox settings](/docs/api/mailboxes/patch_IdentityUpdate) in the API reference.

## Example

```ts
const mailbox = await openemail.identities.update(identityId, {})
```

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `identityId` | `string` | Identity ULID identifier. The path's `{identityId}`. |
| `body` | [`IdentitiesUpdateBody`](#identitiesupdatebody) | Optional. The request's body. |

## Options

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

| Option | Type | Sent as | Description |
| --- | --- | --- | --- |
| `idempotencyKey` | `string` | header `idempotency-key` | A control PATCH's (suspended, receiveHold) idempotency key, 1 to 128 characters, unique per gesture. A retry with the same key is recognised and never written again: it answers the state as it stands (200, 202, or 409 suspension_changed / receive_hold_changed if a newer different change won), so a lost answer or a 503 can be retried without reasserting this change over someone else's. The same key asking for another value is 409 idempotency_key_reused. On a settings PATCH it is 400 idempotency_key_unsupported |

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, [`Mailbox`](/docs/sdks/typescript/types/mailbox). 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, ephemeral_immutable (ephemeral named in a PATCH: it is fixed at creation), invalid_address, unknown_domain, domain_is_alias, address_not_routed, or semantic_floor_with_opt_out (semantic: false and semanticFloor in one request); control_exclusive (suspended or receiveHold alongside any other field, or both together); not_suspendable (suspended on a platform identity, which belongs to no account); not_holdable (receiveHold on one); idempotency_key_invalid (empty or over 128 characters); idempotency_key_unsupported (an Idempotency-Key on a settings PATCH) |
| `401` | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge |
| `403` | system_credentials_required (a send-policy field from a non-system caller); or semantic_not_enabled — semantic: true, or semanticFloor, without the account's plan gate. Every semantic refusal is decided BEFORE any other field is written; or suspension_not_enabled (suspended from an account key while this deployment has not enabled owner suspension); or receive_hold_not_enabled (receiveHold from an account key while this deployment has not enabled the owner's receive hold) |
| `404` | Mailbox not found or not accessible to this principal |
| `409` | semantic_not_enabled — semanticFloor given while semantic search is off; or no_mail_store: semantic: true or semanticFloor on an identity without a mail store, which has no mail to index (semantic: false is what it already is, and is accepted); or suspension_changed: a newer opposite suspend or resume superseded this one before it completed: the body's `mailbox` carries the current fields; or receive_hold_changed: a newer different receiveHold superseded this one before it completed, the body's `mailbox` carrying the current fields; or idempotency_key_reused: this Idempotency-Key was already used asking for another value, nothing changed, use a fresh key for a new gesture |
| `413` | too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing |
| `503` | semantic_capacity, when every vector shard is closed to new assignment: nothing changed; Retry-After carries an hour. Or temporary_failure: under the object directory, semantic: true was asked for while the fleet's shard counts could not be read consistently (a bucket move, or semantic facts still backfilling); nothing changed; retry after the Retry-After window. Or temporary_failure (with Retry-After): under the object directory, the account's identity census could not be updated just now, so the write that would move it was not made; retry the same request after the Retry-After window (a send hold or its release; fields applied before it stand, and the retry converges). Or temporary_failure for a control (suspended, receiveHold) when the authority refused the write before committing it: nothing changed; retry, with the same Idempotency-Key |

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

### IdentitiesUpdateBody

```ts
/** The body of `identities.update`. */
type IdentitiesUpdateBody = {
  /** Create the mailbox DISPOSABLE (#483): its DELETE destroys it at once — no undo record, no 7-day window, its object gone, the address free again immediately — the shape for a mailbox per support case, agent session or transaction. Fixed at creation and reported on every read; a PATCH naming it is refused 400 ephemeral_immutable in either direction, so a key cannot make a long-lived mailbox disposable after the fact. Omitted or false creates an ordinary mailbox. Refused 400 ephemeral_requires_account on a platform identity, which has no account home to destroy through */
  ephemeral?: boolean
  /** System callers only. Outbound recipient allowlist: the ONLY addresses this mailbox may send to. Entries are exact addresses (`jo@acme.dev`) or domain wildcards (`*@acme.dev`). `null` = unrestricted (the default); `[]` = may send to nobody. At most 1,000 entries of at most 320 characters each (400 validation_failed otherwise); a list stored before these limits keeps working. A refused submission answers 403 recipient_not_permitted — permanent, so SMTP submission gets a 550. EGRESS ONLY: a restricted mailbox still receives from anyone */
  permittedRecipients?: string[] | null
  /** On create: CLAIMS the address - the address→mailbox route and the label are created atomically with the mailbox (409 address_taken if already routed); must be an ASCII local part on a non-alias directory domain owned by the mailbox's account (a U-label domain spelling is canonicalized to its stored A-label). On update: selects among the mailbox's already-routed addresses (bind first via POST /routes, which is idempotent); null clears the label */
  primaryAddress?: string | null
  quotaBytes?: number | null
  /** Hold the mailbox's RECEIVING, the account owner's control, independent of suspension: 'paused' tells every sender to retry later (429 receiving_paused, SMTP 451; senders give up after about four to five days, after which their mail bounces and is lost, so a pause is for interruptions measured in days), 'disabled' rejects mail to it at once (403 receiving_disabled, SMTP 550; a rejection already issued cannot be undone), null receives normally again. Existing mail, settings and logins are untouched. Must be the ONLY field of its request (400 control_exclusive otherwise). A change of mode restamps receiveHoldAt; re-sending the current value keeps it and completes any propagation still pending */
  receiveHold?: ('paused' | 'disabled') | null
  /** SEMANTIC (meaning-based) search for this mailbox (docs/semantic-search-design.md). true embeds every new message after delivery and, on an existing mailbox, backfills a recent window (the later of 12 months and the 20,000 most recent messages; older mail on request via semanticFloor); false DELETES the mailbox's embeddings. Requires the account's plan gate (403 semantic_not_enabled) and an open shard (503 semantic_capacity). Off by default */
  semantic?: boolean
  /** 'Index older mail': LOWERS the semantic backfill floor to this epoch second (null = the whole store). Never raises it. Requires semantic search to be on (409 semantic_not_enabled); refused on create, where the floor is the creation instant */
  semanticFloor?: number | null
  /** System callers only. Operator enforcement over this mailbox's outbound mail. 'disabled' STOPS it: every submission is refused 403 sending_disabled, queued relay jobs are dropped at the relay, and vacation auto-replies stop — permanent by contract, so SMTP submission gets a 550 and the mail bounces. 'paused' HOLDS it, the reversible form for a suspension you intend to lift (non-payment, an investigation): submissions answer 429 sending_paused with Retry-After, so SMTP submission gets a 451 and the sender's MTA queues the mail; queued relay jobs are DEFERRED rather than bounced. null lifts either. Does not affect receiving or reading. Applies to work already accepted as well: a send in progress stops before its remaining recipients, and queued group fan-out, member deliveries, destination webhooks and forwarding legs from this sender's submissions are deferred under 'paused' and dropped under 'disabled'. Already-queued fan-out legs may run for up to 10 seconds after the change. A retry with the same X-Delivery-Id is refused while the hold is set. */
  sendHold?: ('disabled' | 'paused') | null
  /** System callers only. Distinct messages this mailbox may send per rolling 24h. null = the platform default; 0 = unlimited */
  sendMsgsPerDay?: number | null
  /** System callers only. The BURST window: distinct messages this mailbox may send per hour (measured over the current and previous hourly bucket, so a refusal can hold for up to ~2h after a burst). null = the platform default; 0 = unlimited */
  sendMsgsPerHour?: number | null
  /** System callers only. Envelope recipients this mailbox may send to per rolling 24h. null = the platform default; 0 = unlimited */
  sendRcptsPerDay?: number | null
  /** System callers only. The BURST window: envelope recipients this mailbox may send to per hour. null = the platform default; 0 = unlimited */
  sendRcptsPerHour?: number | null
  /** Suspend (true) or resume (false) the mailbox: the account owner's control over a person's mailbox. A suspended mailbox's logins are refused as a wrong password is, its sending is held and its open sessions end; it keeps receiving mail, its credentials and settings are kept, and its owner keys still read and administer it. Must be the ONLY field of its request (400 control_exclusive otherwise). Re-sending the current value keeps suspendedAt and completes any enforcement still pending */
  suspended?: boolean
}
```

It names these types of the API, each on a page of its own: [`Mailbox`](/docs/sdks/typescript/types/mailbox).
