bird email mailboxes compose

Usage

Code example

bird email mailboxes compose <mailbox-id> [flags]

Description

Send a new message from a mailbox

Sends from the mailbox's own address and starts a new conversation. Replies thread back into it automatically. To reply within an existing conversation, use bird email threads messages reply instead.

Build the request from flags, a JSON EmailMailboxComposeRequest body via --body-file ("-" reads stdin), or both — a flag overrides the matching body field. Run --example to print a ready-to-edit body, or --dry-run to print the resolved request without sending it.

Examples

Code example

# print the body shape (no credentials needed)
bird email mailboxes compose --example

# the body it prints:

Code example

{
  "subject": "Your quote",
  "text": "Hi, here is the quote you asked for.",
  "to": ["delivered@messagebird.dev"]
}

Code example

# preview the resolved request without sending
bird email mailboxes compose <mailbox-id> --to alice@example.com --subject "Hi" --text "Hello" --dry-run

Options

Recipients

Name	Description
--to <value>…	Recipient address; repeatable. Accepts bare addresses or RFC 5322 "Name <addr>" form
--cc <value>…	CC recipient; repeatable. Accepts bare addresses or RFC 5322 "Name <addr>" form
--bcc <value>…	BCC recipient; repeatable. Accepts bare addresses or RFC 5322 "Name <addr>" form
--reply-to <value>…	Reply-To address; repeatable. Defaults to the mailbox's own default-reply-to

Content

Name	Description
--subject	Subject line
--html	HTML body
--text	Plain-text body

Labels & metadata

Name	Description
--tag <key=value>	Tag as name=value; repeatable
--metadata	Arbitrary JSON metadata object

Delivery

Name	Description
--category	Suppression policy: marketing or transactional; defaults to transactional

Request

Name	Description
--body-file	Read the JSON request body from this file; "-" reads stdin
--example	Print a complete example request body, then exit
--dry-run	Print the resolved request without sending it, then exit
--idempotency-key	Deduplication key; a retry with the same key won't act twice

Options

Name	Description
--response-schema	Print the fields this command returns, then exit

Name	Description
bird email mailboxes create	Create a mailbox
bird email mailboxes delete	Delete a mailbox
bird email mailboxes get	Get a mailbox
bird email mailboxes labels	List a mailbox's labels
bird email mailboxes list	List mailboxes
bird email mailboxes restore	Restore a deleted mailbox
bird email mailboxes resume	Resume a suspended mailbox
bird email mailboxes stats	Get mailbox email statistics
bird email mailboxes update	Update a mailbox

Related resources

Continue with the documentation, guides and examples for this topic. Resources are in English.

Watch the guideSetting up your coding agent Understand the conceptWhat is an MCP server, and how does an agent use one to send messages?Explore the capabilityCoding agents Follow the learning pathBuild with AI agents

Get an implementation brief