credentials.create
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
| Argument | Type | Description |
|---|---|---|
identityId | string | Mailbox identity ULID. The path's {identityId}. |
body | CredentialsCreateBody | The 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
| Status | What it means |
|---|---|
400 | validation_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) |
401 | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a WWW-Authenticate: Bearer challenge |
403 | invalid_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) |
404 | Mailbox not found or not accessible to this principal |
409 | no_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) |
413 | too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing |
429 | rate_limited — too many self-service attempts |
503 | temporary_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 | CredentialsCreateBodyAppPasswordCredentialsCreateBodyPassword
/** 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.