<Intro>

<EndpointHeader />

<Description>

Restores a mailbox deleted less than 30 days ago. The address is bound back to the mailbox and starts receiving again, and the remembered messages and conversations are available as before the delete. Once the 30-day window has passed the mailbox and its messages are permanently deleted and can no longer be restored (404). Restoring a mailbox that is not deleted returns a conflict, as does an address that is no longer available.

</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>