CLI

Send your first email from a macOS or Linux terminal: install the bird CLI, log in once, and send. You do not need to copy an API key.

1. Install

Code example

curl -fsSL https://cli.bird.com/install.sh | sh

Run bird version to confirm that the installation succeeded. For Windows and other installation options, see Install the CLI.

2. Log in

Code example

bird auth login --scope emails:write

This opens a browser consent page where you choose a workspace and approve the grant. The emails:write scope lets step 3 send. Without it, bird auth login requests read-only access and the send is refused. The CLI stores a workspace-bound OAuth token in ~/.config/bird/credentials.json, refreshes it when needed, and records the workspace region.

3. Send an email

Send from Bird's shared onboarding domain to the delivered@messagebird.dev sandbox address: no domain verification, no real mailbox needed.

Code example

bird email send \
  --from onboarding@messagebird.dev \
  --to delivered@messagebird.dev \
  --subject "Hello from Bird" \
  --html "<p>My first Bird email.</p>"

The CLI prints the accepted message as JSON. The *_count fields track recipients through the delivery states. In the initial response, one recipient is accepted and none are delivered:

Code example

{
  "id": "em_01ky7ma8y2es1s2akzk53tmjn0",
  "status": "accepted",
  "category": "marketing",
  "from": { "email": "onboarding@messagebird.dev" },
  "to": [{ "email": "delivered@messagebird.dev" }],
  "subject": "Hello from Bird",
  "accepted_count": 1,
  "processed_count": 0,
  "delivered_count": 0,
  "deferred_count": 0,
  "bounced_count": 0,
  "complained_count": 0,
  "rejected_count": 0,
  "open_count": 0,
  "click_count": 0,
  "track_opens": true,
  "track_clicks": true,
  "created_at": "2026-07-23T13:58:20.866Z"
}

--to is repeatable for multiple recipients, --text sends a plain-text body, and --dry-run prints the resolved request without sending it.

4. Check the result

accepted means Bird took the message and delivers it asynchronously. Read it back by its em_ ID and watch the status reach delivered:

Code example

bird email get em_01ky7ma8y2es1s2akzk53tmjn0

Add --format text for a human-readable card instead of JSON.

Every command writes JSON to standard output by default. Errors use a JSON envelope on standard error, and exit codes identify failure categories. See the CLI for agents for the full contract.

Next steps

CLI reference: install, authentication, the output contract, and the main command groups.
The CLI for agents: JSON output, exit codes, --dry-run, and idempotent retries.
Send your first email: the same flow over raw HTTP and the SDKs.
Sending domains: verify your own domain for production sending.

Related resources

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

Watch the guideTesting email without spamming anyone Explore the capabilityTest email delivery Follow the learning pathOperate messaging reliably

Try the practice and get an implementation brief