Sign inGet Started
Get started
Guides
API Reference
SDKs
CLI
Knowledge Base
Changelog

Update a mailbox

PATCH
/v1/email/mailboxes/{mailbox_id}
const mailbox = await bird.email.mailboxes.update("mbx_01abc", {
  receive_policy: "open",
});
console.log(mailbox.id, mailbox.receive_policy);
Response200
{
  "id": "mbx_01krdgeqcxet5s7t44vh8rt9mg",
  "address": "concierge@inbox.ai",
  "display_name": "Acme Concierge",
  "receive_policy": "open",
  "state": "active",
  "channel": "email",
  "owner": {
    "type": "workspace",
    "id": "ws_01krdgeqcxet5s7t44vh8rt9mg"
  },
  "inbound_address_id": "ina_01krdgeqcxet5s7t44vh8rt9mg",
  "retention_tier": "30d"
}

Updates a mailbox. The address and domain are immutable. Lowering the retention tier makes remembered messages older than the new cutoff eligible for deletion. If any exist, the request requires confirm=true. A tier change is applied to the mailbox's stored messages in the background; lowering the tier again while that is still being applied is refused with E17050. You can still raise it to a tier your plan permits.

Parameters

mailbox_idstring

Mailbox identifier. Starts with mbx_.

Query Parameters

confirmboolean

Set to true when lowering retention_tier would make remembered messages older than the new cutoff eligible for deletion. The request is rejected without it in that case.

Request Payload

display_name
nullable string

Display name used as the sender name on mail from this mailbox. null clears it.

default_reply_to
nullable string

Default Reply-To address stamped on mail sent from this mailbox. null clears it.

receive_policy
string

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. Landing in an existing thread by itself does not count.
  • allowlist: Accepts only senders matching an allow rule.
  • drop: Stores nothing.

Possible values: open, replies_only, allowlist, drop

retention_tier
string

How long message metadata, extracted text, and attachments are kept. Original bodies and inbound raw MIME are limited to 30 days on every tier. Longer tiers require a plan that includes them. Lowering the tier requires confirm=true when messages would be affected; accepted changes hide those messages immediately. Deletion waits at least ten minutes and until the retention update finishes.

Possible values: 30d, 90d, 1y

metadata
object

Replaces the mailbox's key/value data. Up to 2 KB. Keys starting with __bird are reserved.

Response Payload

id
string
required

Mailbox ID.

address
string
required

The mailbox's email address. Immutable once created.

display_name
nullable string
required

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

default_reply_to
nullable string
required

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

receive_policy
string
required

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. Landing in an existing thread by itself does not count.
  • allowlist: Accepts only senders matching an allow rule. Replies to prior outbound mail are always admitted unless blocked.
  • drop: Stores nothing.

Possible values: open, replies_only, allowlist, drop

state
string
required

Lifecycle state. active means the mailbox can send, receive, and expose conversations. suspended pauses sending, conversation reads, and events; inbound mail is retained with the blocked label until you resume it.

Possible values: active, suspended

channel
string
required

The channel this mailbox receives on. Always email.

Possible values: email

owner
object
required

The principal that owns the mailbox. Always the workspace.

Show child attributes
owner.type
string
required

Owner principal type.

Possible values: workspace

owner.id
string
required

Owner principal ID.

inbound_address_id
string
required

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

retention_tier
string
required

How long message metadata, extracted text, and attachments are kept. Original bodies and inbound raw MIME are limited to 30 days on every tier.

Possible values: 30d, 90d, 1y

message_count
integer
required

Number of retained messages across all threads.

thread_count
integer
required

Number of retained threads.

size_bytes
integer
required

Stored bytes across the mailbox's retained messages: subject, preview, extracted text, and attachment bytes. Message bodies and raw MIME expire after 30 days and do not count. Maintained with each message written or deleted, so the value is current; messages stored before the counter existed are not counted.

unread_thread_count
nullable integer

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

metadata
object
required

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

local_part_generated
boolean
required

Whether we 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.

created_at
string
required

When the mailbox was created.

updated_at
string
required

When the mailbox was last updated.

deleted_at
nullable string

When the mailbox was deleted, or null if active. Deletion stops receiving; restore is available for 30 days unless permanent erasure has started.

Related resources

Continue with the documentation, guides and examples for this topic.

Get an implementation brief