Skip to Content

Create an identity.

An identity is a principal in an account: it owns stores (a mail store, calendars, contacts), holds credentials, and can be shared with. It takes one of two shapes at creation.

With primaryAddress (the common case): the address is claimed and routed to the identity atomically, the mail store is bound, and the initial labels are provisioned. The identity receives mail at once and logs in with the address as its username.

With withoutAddress: true: no email address and no mail store, so it receives no mail and every mail route (messages, labels, uploads, search, filters, sharing) answers 404 for it, while the identity routes (credentials, settings, delete and restore) and its calendars and contacts work as for any identity. There is no login until a credential is minted with an explicit username (POST /api/v1/identities/{identityId}/credentials), since there is no address to default to; the username is a bare name without @. Routing an address to it later (POST /api/v1/routes or /api/v1/patterns, destinationType mailbox, or a retarget of either) gives it a mail store in that write, and it then receives mail like any other identity; nothing undoes that, a later route delete included. semantic: true is refused on it (400 no_mail_store), since there is no mail to index. Until then it holds events, tasks and contacts and takes part in sharing, but not in scheduling: iCalendar names participants by mailto: address, so it can neither invite nor be invited.

A create with neither is refused 400 primary_address_required; both together is 400 without_address_has_address.

receiveHold creates the mailbox already holding its receiving (paused or disabled), committed with the identity and its address so it applies from the first arrival; the answer carries receiveHold, receiveHoldAt and receiveHoldPending as GET does. On a withoutAddress create the hold is the identity's until an address is routed to it, and the mail store that write gives it holds from its first arrival.

messageWebhook and eventWebhook configure, in the same request, the mailbox's message webhook (every message that lands in the mailbox, however it was routed, POSTed beside its normal delivery; managed afterwards at /api/v1/mailboxes/{mailboxId}/message-webhook) and the identity's mailbox-scope event webhook, so the identity never exists without them. Each is optional; with neither the request and answer are exactly as above. Both are an account's: a platform identity takes neither (409 account_required). A create naming either requires an Idempotency-Key header (1 to 128 characters), which names one creation: a retry with the same key and body answers the same identity as it now is, never re-applying either webhook over a later change; any other body under the key is refused 409 idempotency_key_reused; and an identity deleted since is never re-created (409 identity_deleted). A completed creation answers its key for 30 days, the retry window. The 200 comes once the identity, its route, each webhook and its mail store's arming are in place. Until then the answer is 503 temporary_failure with Retry-After, mail to the address is refused as temporary (SMTP 451) and the identity's calendar and contact writes too, and the setup completes in the background whether or not the request is retried. Nothing is sent to either URL at creation.

openemail.identities.create(
  body?: IdentitiesCreateBody,
  options?: CallOptions,
): ApiPromise<CreatedIdentity>

It calls POST /identities: Create an identity in the API reference.

Example

const createdIdentity = await openemail.identities.create({
  eventWebhook: {
    secret: 'whsec_events_3f6b8d1a9c4e2f7b',
    url: 'https://hooks.acme.example/events',
  },
  messageWebhook: {
    format: 'parsed',
    secret: 'whsec_message_7c2e9a4f1b8d3e6a',
    url: 'https://hooks.acme.example/incoming',
  },
  primaryAddress: 'agent@acme.example',
})

Arguments

ArgumentTypeDescription
bodyIdentitiesCreateBodyOptional. 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, CreatedIdentity. It is an ApiPromise: .withResponse() gives the same with the Response it came in, for its headers.

Errors

StatusWhat it means
400validation_failed, ephemeral_requires_account (ephemeral: true on a platform identity), unknown_account, invalid_address, unknown_domain, domain_is_alias, primary_address_required (no primaryAddress and withoutAddress not true; and a DOMAIN-SCOPED api key must create WITH an address on one of its domains, withoutAddress or not: a bare identity would be one it could never reach again, migration 0078), without_address_has_address (withoutAddress: true with a primaryAddress), no_mail_store (semantic: true with withoutAddress: true: no mail to index), not_holdable (receiveHold on a platform identity, which belongs to no account), message_webhook_requires_address (messageWebhook with withoutAddress: true), webhook_format_unavailable (messageWebhook.format reference on a deployment that mints no capability URLs), idempotency_key_required (messageWebhook or eventWebhook without an Idempotency-Key) or idempotency_key_invalid (empty or over 128 characters)
401unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a WWW-Authenticate: Bearer challenge
403mailbox_limit_reached — the account's maximum mailbox limit has been reached; address_blocked — the primary address, its tag-stripped form, or its domain is on the platform blocklist (migration 0070); semantic_not_enabled — semantic: true was asked for without the account's plan gate; or receive_hold_not_enabled (receiveHold from an account key while this deployment has not enabled the owner's receive hold)
409address_taken — the primary email address is already routed to another mailbox — or account_deleted (the owning account is soft-deleted; restore it first), account_required (messageWebhook or eventWebhook on a platform identity: webhooks at creation are an account's), idempotency_key_reused (this Idempotency-Key belongs to a create with another request body; nothing changed), or identity_deleted (the identity this Idempotency-Key created was deleted since; a retry never re-creates it, use a fresh key)
413too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing
429rate_limited — account daily mailbox creation limit exceeded
503semantic_capacity, when semantic: true was asked for but every vector shard is closed to new assignment: nothing was created, retry without the flag or once a shard is open. 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 was created; retry after the Retry-After window. Or temporary_failure on a create with messageWebhook or eventWebhook whose setup has not finished (its initialization, the event webhook or the mail store's arming): the identity is reserved and its setup is completed in the background; mail to its address is refused as temporary and its calendar and contact writes too until it is; retry with the same Idempotency-Key and body, which never creates a second identity. 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 failed call rejects with a RequestError: its status, and its code, the API's error. Decide on the code: one status covers several.

Types

IdentitiesCreateBody

/** The body of `identities.create`. */
type IdentitiesCreateBody = {
  /** Owning account (system callers only; account callers always own their mailboxes) */
  accountId?: string
  /** 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
  /** The identity's mailbox-scope event webhook, as PUT /api/v1/mailboxes/{mailboxId}/event-webhook configures it: one URL, every supported event, batched and signed. Allowed with withoutAddress: true, for calendar and contact notifications. Requires an owning account (409 account_required on a platform identity). Manage it afterwards at /api/v1/mailboxes/{mailboxId}/event-webhook. Omitted or null configures none. Requires an Idempotency-Key */
  eventWebhook?: IdentitiesCreateBodyEventWebhook | null
  /** The mailbox's message webhook: every message that lands in the mailbox is POSTed here (the incoming-email payload, its signing and retries) beside its normal delivery, however it got there: its primary address, any address routed to it later, a pattern or catch-all, a group, a forward, a delivery-status or platform notice. Requires a primaryAddress (400 message_webhook_requires_address with withoutAddress: true) and an owning account (409 account_required on a platform identity). Manage it afterwards at /api/v1/mailboxes/{mailboxId}/message-webhook. Omitted or null configures none. Requires an Idempotency-Key */
  messageWebhook?: IdentitiesCreateBodyMessageWebhook | null
  /** 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
  /** Create the mailbox already holding its receiving: 'paused' (senders retry for about four to five days, then their mail bounces and is lost) or 'disabled' (mail to it is rejected at once). The hold commits with the identity and its address, so it applies from the first arrival. Omitted or null creates a receiving mailbox. The account owner's control, like PATCH receiveHold: refused 400 not_holdable on a platform identity, and 403 receive_hold_not_enabled from an account key while this deployment has not enabled it */
  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
  /**
   * Create the identity with no email address and no mail store: it receives no mail, and every mail route answers 404 for it; its calendars and contacts work as for any identity. An identity is created WITH a primaryAddress unless this is true: a create with neither is refused 400 primary_address_required, and true with a primaryAddress is refused 400 without_address_has_address, both before anything is written. Omitted or null is false. A domain-scoped api key never creates one: without an address it is refused 400 primary_address_required, withoutAddress or not. There is no login until a credential is minted with an explicit username, and routing an address to it later makes it receive mail like any other identity
   * @default false
   */
  withoutAddress?: boolean | null
}

IdentitiesCreateBodyEventWebhook

/** The identity's mailbox-scope event webhook, as PUT /api/v1/mailboxes/{mailboxId}/event-webhook configures it: one URL, every supported event, batched and signed. Allowed with withoutAddress: true, for calendar and contact notifications. Requires an owning account (409 account_required on a platform identity). Manage it afterwards at /api/v1/mailboxes/{mailboxId}/event-webhook. Omitted or null configures none. Requires an Idempotency-Key */
type IdentitiesCreateBodyEventWebhook = {
  /** HMAC signing secret, 1 to 256 characters, write-only. Omitted or null: unsigned */
  secret?: string | null
  /** HTTPS endpoint on a public host */
  url: string
}

IdentitiesCreateBodyMessageWebhook

/** The mailbox's message webhook: every message that lands in the mailbox is POSTed here (the incoming-email payload, its signing and retries) beside its normal delivery, however it got there: its primary address, any address routed to it later, a pattern or catch-all, a group, a forward, a delivery-status or platform notice. Requires a primaryAddress (400 message_webhook_requires_address with withoutAddress: true) and an owning account (409 account_required on a platform identity). Manage it afterwards at /api/v1/mailboxes/{mailboxId}/message-webhook. Omitted or null configures none. Requires an Idempotency-Key */
type IdentitiesCreateBodyMessageWebhook = {
  /** The payload shape: parsed (the default) or reference (headers plus a capability rawUrl; 400 webhook_format_unavailable where the deployment mints none) */
  format?: ('parsed' | 'reference') | null
  /** HMAC signing secret, write-only. Omitted or null: the tap is unsigned */
  secret?: string | null
  /** HTTPS endpoint on a public host */
  url: string
}

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