Skip to Content

The Mailbox type of the TypeScript SDK, which identities.update take or answer.

type Mailbox = {
  accountId: string | null
  createdAt: number
  ephemeral: boolean
  groupAddress: string | null
  hasMailStore: boolean
  id: string
  permittedRecipients: string[] | null
  primaryAddress: string | null
  provisioningPending?: boolean
  quotaBytes: number | null
  receiveHold: ('paused' | 'disabled') | null
  receiveHoldAt: number | null
  receiveHoldPending: boolean
  retentionDays: number | null
  semantic: boolean
  sendHold: ('disabled' | 'paused') | null
  sendMsgsPerDay: number | null
  sendMsgsPerHour: number | null
  sendRcptsPerDay: number | null
  sendRcptsPerHour: number | null
  suspendedAt: number | null
  suspensionPending: boolean
}

Fields

FieldTypeDescription
accountIdstring | nullAccount ID owning this mailbox, or null
createdAtnumberCreation timestamp in epoch seconds
ephemeralbooleanWhether the mailbox was created DISPOSABLE (ephemeral: true at creation, immutable afterwards): its DELETE destroys it at once — no undo record, no 7-day window, the address free again immediately. False for every ordinary mailbox, whose DELETE keeps the window
groupAddressstring | nullWhen this identity is a GROUP PERSONA, the group address whose archive it keeps and which it may send as; null for every other identity. A persona has no primaryAddress, cannot be a route target, refuses its own DELETE (delete the group route instead) and its Sieve/rules writes, and is exempt from max_mailboxes
hasMailStorebooleanWhether this identity has the mail capability. False for a calendar/contacts-only identity; true may also have a null primaryAddress. Derived from the directory row without reading or provisioning a store, not an indication that the store has been initialized or contains messages
idstringUnique mailbox ULID
permittedRecipientsstring[] | nullThis mailbox's outbound recipient allowlist, written by system callers only. Entries are exact addresses (jo@acme.dev) or domain wildcards (*@acme.dev). null = unrestricted (the default); [] = may send to nobody. A submission outside the list is refused with 403 recipient_not_permitted (SMTP 550). Egress only: receiving is unaffected. A credential's own permittedRecipients may restrict sending further
primaryAddressstring | nullPrimary email address assigned to this mailbox, or null if none
provisioningPendingbooleanOptional. Present, true, only while this identity's creation with messageWebhook or eventWebhook is still setting up: mail to its address and its calendar and contact writes are refused as temporary (503 temporary_failure) until it is, and the setup completes in the background. Absent for every other identity
quotaBytesnumber | nullStorage quota in bytes, or null for unlimited
receiveHold('paused' | 'disabled') | nullThe account owner's hold on this mailbox's RECEIVING, independent of suspension and of sendHold: 'paused' = senders are told to retry later (429 receiving_paused, SMTP 451; they give up after about four to five days, so a pause is for short interruptions), 'disabled' = mail to it is rejected at once (403 receiving_disabled, SMTP 550), null = receiving. Set with PATCH {"receiveHold": "paused"|"disabled"|null}, or on create
receiveHoldAtnumber | nullWhen the current receiveHold was set (epoch seconds), restamped when the mode changes; null while receiving. The age of a pause is what decides whether it is still a pause: warn from the third day
receiveHoldPendingbooleanWhether the current receiveHold has not yet reached the mailbox's store: true right after a change still being applied (PATCH answered 202), false once it holds. Poll until false
retentionDaysnumber | nullThe mailbox's OWN time-based retention window in days (null = none; the account default applies if one is set). The window in force, with a preview, is GET /mailboxes/:id/retention
semanticbooleanWhether SEMANTIC (meaning-based) search is enabled for this mailbox: messages are embedded after delivery and GET /mailboxes/:id/search/semantic and …/messages/:id/similar answer. Tenant-set, gated by the account's plan; off by default. Turning it off DELETES the mailbox's embeddings
sendHold('disabled' | 'paused') | nullThis mailbox's own operator enforcement: 'disabled' = permanent stop (403 sending_disabled), 'paused' = reversible hold (429 sending_paused), null = neither. System-written only
sendMsgsPerDaynumber | nullDaily outbound message limit (null = platform default, 0 = unlimited)
sendMsgsPerHournumber | nullHourly (burst) outbound message limit (null = platform default, 0 = unlimited)
sendRcptsPerDaynumber | nullDaily outbound recipient limit (null = platform default, 0 = unlimited)
sendRcptsPerHournumber | nullHourly (burst) outbound recipient limit (null = platform default, 0 = unlimited)
suspendedAtnumber | nullWhen the account owner suspended this mailbox (epoch seconds), null when it is not suspended. While suspended its logins are refused as a wrong password is, its sending is held (429 sending_paused) and its open sessions end; it still receives mail, and its owner keys can still read and administer it. Set with PATCH {"suspended": true|false}
suspensionPendingbooleanWhether the current suspendedAt has not yet reached every core gate it must: true right after a change whose enforcement is still being applied (PATCH answered 202), false once it holds everywhere. Poll until false

Used by

MethodWhat it does
identities.updateUpdate mailbox settings

Used in

Identity, MailboxWithStats, MailboxWithUsage.