<Intro>

<EndpointHeader />

<Description>

Returns a single mailbox by ID. A mailbox deleted within its 30-day restore window is still returned, with a non-null `deleted_at`; once the window closes it is permanently removed and returns 404.

</Description>

</Intro>

<Payload kind="response">

<Field name="id" type="string" required>

<Description>

Mailbox ID.

</Description>

</Field>

<Field name="address" type="string" required>

<Description>

The mailbox's email address. Immutable once created.

</Description>

</Field>

<Field name="display_name" type="nullable string" required>

<Description>

Display name used as the sender name on mail from this mailbox. Null when unset.

</Description>

</Field>

<Field name="default_reply_to" type="nullable string" required>

<Description>

Default Reply-To address stamped on mail sent from this mailbox. Null when unset.

</Description>

</Field>

<Field name="receive_policy" type="string" required>

<Description>

Which inbound mail the mailbox accepts. `open` accepts everything not blocked by a rule; `replies_only` accepts only replies to messages this mailbox has sent (a reply must match a message the mailbox sent, not merely land in an existing thread); `allowlist` accepts only senders matching an allow rule (replies to prior outbound are always admitted unless blocked); `drop` stores nothing.

</Description>

<Description>

Possible values: `open`, `replies_only`, `allowlist`, `drop`

</Description>

</Field>

<Field name="state" type="string" required>

<Description>

Lifecycle state. Suspended mailboxes stop emitting events; inbound mail is retained as blocked.

</Description>

<Description>

Possible values: `active`, `suspended`

</Description>

</Field>

<Field name="channel" type="string" required>

<Description>

The channel this mailbox receives on. Always `email`.

</Description>

<Description>

Possible values: `email`

</Description>

</Field>

<Field name="owner" type="object" required>

<Description>

The principal that owns the mailbox. Always the workspace.

</Description>

<FieldChildren kind="response">

<Field name="type" type="string" prefix="owner." required>

<Description>

Owner principal type.

</Description>

<Description>

Possible values: `workspace`

</Description>

</Field>

<Field name="id" type="string" prefix="owner." required>

<Description>

Owner principal ID.

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="inbound_address_id" type="string" required>

<Description>

The underlying inbound address that receives this mailbox's mail.

</Description>

</Field>

<Field name="retention_tier" type="string" required>

<Description>

How long the mailbox remembers message metadata and extracted text. Original rendered source (HTML, raw message, attachments) is always available for 30 days regardless of tier. `3y` and `10y` are reserved future tiers.

</Description>

<Description>

Possible values: `30d`, `90d`, `1y`

</Description>

</Field>

<Field name="message_count" type="integer" required>

<Description>

Number of retained messages across all threads.

</Description>

</Field>

<Field name="thread_count" type="integer" required>

<Description>

Number of retained threads.

</Description>

</Field>

<Field name="unread_thread_count" type="nullable integer">

<Description>

Number of threads with unread messages in this mailbox, excluding trash. Null on create/update responses.

</Description>

</Field>

<Field name="metadata" type="object" required>

<Description>

Your own key/value data attached to the mailbox. Up to 2 KB; keys starting with `__bird` are reserved.

</Description>

</Field>

<Field name="local_part_generated" type="boolean">

<Description>

Whether Bird generated the local part of the address. `false` means a custom handle was chosen at creation; on the shared `inbox.ai` domain a custom handle counts against your plan's custom-handle allowance.

</Description>

</Field>

<Field name="created_at" type="string" required>

<Description>

When the mailbox was created.

</Description>

</Field>

<Field name="updated_at" type="string" required>

<Description>

When the mailbox was last updated.

</Description>

</Field>

<Field name="deleted_at" type="nullable string">

<Description>

When the mailbox was deleted, or null if it is active. A deleted mailbox stops receiving mail immediately but can be restored for 30 days, after which it and its remembered messages are permanently removed.

</Description>

</Field>

</Payload>