Skip to Content

Reset a mailbox password as an administrator.

Sets a new password on every password credential the mailbox has, creating one if it has none (named after the primary address, or the group address for a group persona), and revokes every expiring credential (browser sessions) so nothing minted before the reset survives it. App passwords are kept unless revokeAppPasswords is set. The mailbox is notified. Callable with an account key or a system key; a mailbox's own bearer uses PUT /password instead, which proves the current password.

openemail.passwords.reset(
  identityId: string,
  body: PasswordsResetBody,
  options?: CallOptions,
): ApiPromise<RecoveryCompleted>

It calls POST /identities/{identityId}/password/reset: Reset a mailbox password as an administrator in the API reference.

Example

const recoveryCompleted = await openemail.passwords.reset(identityId, { newPassword: '…' })

Arguments

ArgumentTypeDescription
identityIdstringMailbox identity ULID. The path's {identityId}.
bodyPasswordsResetBodyThe request's body.

Options

It takes no options of its own. 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, RecoveryCompleted. It is an ApiPromise: .withResponse() gives the same with the Response it came in, for its headers.

Errors

StatusWhat it means
400validation_failed
401unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a WWW-Authenticate: Bearer challenge
404Mailbox not found or not accessible to this principal
409no_username — the identity has no password credential to rotate and no address (primary or group) to name a new one after; nothing was changed. Create the login with POST /credentials and an explicit username
413too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing
503temporary_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 failed call rejects with a RequestError: its status, and its code, the API's error. Decide on the code: one status covers several.

Types

PasswordsResetBody

/** The body of `passwords.reset`. */
type PasswordsResetBody = {
  /** The password to set */
  newPassword: string
  /** Revoke the mailbox's non-expiring app passwords too. Off by default, on when the reset is a response to a compromise rather than to a forgotten password */
  revokeAppPasswords?: boolean
}

It names these types of the API, each on a page of its own: RecoveryCompleted.