Skip to Content

Create mailbox credential.

Creates an IMAP login password or generates a scoped API app password for a mailbox.

openemail.credentials.create(
  identityId: string,
  body: CredentialsCreateBody,
  options?: CallOptions,
): ApiPromise<CredentialCreated>

It calls POST /identities/{identityId}/credentials: Create mailbox credential in the API reference.

Example

const credentialCreated = await openemail.credentials.create(identityId, { kind: 'password', password: '…' })

Arguments

ArgumentTypeDescription
identityIdstringMailbox identity ULID. The path's {identityId}.
bodyCredentialsCreateBodyThe 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, CredentialCreated. It is an ApiPromise: .withResponse() gives the same with the Response it came in, for its headers.

Errors

StatusWhat it means
400validation_failed, username_required (the identity has no address for the username to default to, as one created withoutAddress has none: name it), invalid_address (D2: an address username must be an ASCII local part on an A-label domain), invalid_username (D2: a bare username must be printable ASCII with no whitespace), username_not_mailbox_address, username_not_in_scope (a DOMAIN-SCOPED api key may only mint a credential whose username is on one of its domains, migration 0078; domain names the refused one), permitted_recipients_requires_send (a recipient list on a credential whose scope is not 'send'), or password_required (the mailbox's own bearer sent no currentPassword)
401unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a WWW-Authenticate: Bearer challenge
403invalid_password (the mailbox's own bearer proved the wrong password), or account_credentials_required (a mailbox bearer asked for a login password: admin only; or a DOMAIN-SCOPED api key named a mailbox that is also routed on a domain outside its scope — a credential outlives the key that minted it, so minting one needs authority over every domain the mailbox serves)
404Mailbox not found or not accessible to this principal
409no_password_credential — the mailbox has no login password to prove, so it cannot self-serve; username_taken: a username that is not an address, already another identity's (under the objects directory)
413too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing
429rate_limited — too many self-service attempts
503temporary_failure: the login index could not take the claim, or the identity could not vouch for itself just now; retry 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

CredentialsCreateBody

/** The body of `credentials.create`. */
type CredentialsCreateBody = CredentialsCreateBodyPassword | CredentialsCreateBodyAppPassword

CredentialsCreateBodyPassword

/** The API's `CredentialsCreateBodyPassword`, as the document describes it. */
type CredentialsCreateBodyPassword = {
  kind: 'password'
  name?: string
  password: string
  /** A login password is always 'full'; any other value is refused */
  scope?: 'full'
  username?: string
}

CredentialsCreateBodyAppPassword

/** The API's `CredentialsCreateBodyAppPassword`, as the document describes it. */
type CredentialsCreateBodyAppPassword = {
  /** Required when the caller is the mailbox's OWN bearer (self-service), ignored for account and system callers: the mailbox's current login password, re-proved because an app password outlives the session that mints it. Refused as password_required (400), invalid_password (403) or no_password_credential (409) */
  currentPassword?: string
  /** Lifetime in seconds. The credential stops authenticating once it elapses: for a client minting one per browser session, so a closed tab cannot leave a permanently valid key behind. Omit for a credential that never expires (the default, and what a mail client wants) */
  expiresInSeconds?: number
  kind: 'app_password'
  name?: string
  /** The credential's OWN outbound recipient allowlist (exact addresses or `*@domain`), INTERSECTED with the identity's: both must permit. Accepted only with scope 'send' (400 permitted_recipients_requires_send otherwise); `[]` means this credential may send to nobody. At most 64 entries of at most 320 characters each (400 validation_failed otherwise). Omit or null for no list of its own */
  permittedRecipients?: string[] | null
  /** The credential's SCOPE (design D50), a ladder — 'read': list and read mail, nothing that leaves a trace; 'write': also mark, file, label and trash (everything the store undoes for 14 days); 'send': also submit mail; 'full' (the default): also permanent deletion, every settings route (rules, Sieve, vacation, prefs, forwarding, shares, retention, pickups, webhooks, credentials — reads included), PIM collection lifecycle and sharing. A call outside the scope answers 403 credential_scope naming the rung it needs. The bound for an agent token: mint 'write' for an assistant that reads and files, 'send' with permittedRecipients for one that may write to named people, and never 'full' for a program */
  scope?: ('read' | 'write' | 'send' | 'full')
  /** System callers only, and IGNORED for anyone else: which frontend this session credential belongs to, recorded on every API-request meter row it produces. The webmail BFF declares `webmail` when it mints a per-session password; a customer's own app password carries nothing, which is what keeps the two distinguishable */
  surface?: ('rest' | 'jmap' | 'dav' | 'gateway' | 'webmail' | 'console' | 'mcp')
  username?: string
}

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