Skip to Content

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.

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

It calls PATCH /identities/{identityId}: Update mailbox settings in the API reference.

Example

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

Arguments

ArgumentTypeDescription
identityIdstringIdentity ULID identifier. The path's {identityId}.
bodyIdentitiesUpdateBodyOptional. The request's body.

Options

The last argument, options, a IdentitiesUpdateOptions, takes:

OptionTypeSent asDescription
idempotencyKeystringheader idempotency-keyA 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).

Answer

Awaited, it is the API's JSON, Mailbox. It is an ApiPromise: .withResponse() gives the same with the Response it came in, for its headers.

Errors

StatusWhat it means
400validation_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)
401unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a WWW-Authenticate: Bearer challenge
403system_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)
404Mailbox not found or not accessible to this principal
409semantic_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
413too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing
503semantic_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: its status, and its code, the API's error. Decide on the code: one status covers several.

Types

IdentitiesUpdateBody

/** 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.