cURL

Send your first email with nothing but curl: export an API key, POST a message, and GET it back to watch it deliver. This is the raw HTTP flow — everything the SDKs do starts here.

1. Export your API key

Create a key in the dashboard under Developers → API keys — the hero quickstart walks through it. Then export it:

Code example

export BIRD_API_KEY="bk_us1_..."

The region prefix picks your API host: bk_us1_ keys call https://us1.platform.bird.com, bk_eu1_ keys call https://eu1.platform.bird.com. The snippets below use us1 — swap the host if your key says otherwise.

2. Send an email

POST to /v1/email/messages, sending from Bird's shared onboarding domain to the delivered@messagebird.dev sandbox address — no domain verification, no real mailbox needed:

Code example

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "onboarding@messagebird.dev",
    "to": ["delivered@messagebird.dev"],
    "subject": "Hello from Bird",
    "html": "<p>My first Bird email.</p>"
  }'

The API responds with 202 immediately — Bird has accepted the email and delivers it asynchronously:

Code example

{
  "id": "em_019c1930687b7bfa8a1b2c3d4e5f6789",
  "status": "accepted",
  "category": "transactional",
  "to": ["delivered@messagebird.dev"],
  "recipient_count": 1,
  "created_at": "2026-06-10T14:30:00Z"
}

Unlike the SDKs, raw HTTP doesn't generate an idempotency key for you — if you retry a POST after a timeout, add an Idempotency-Key: <your-unique-key> header so the retry replays the original result instead of sending twice.

3. Watch it deliver

GET the message by its em_ ID and watch the status move from accepted through processed to delivered:

Code example

curl https://us1.platform.bird.com/v1/email/messages/em_019c1930687b7bfa8a1b2c3d4e5f6789 \
  -H "Authorization: Bearer $BIRD_API_KEY"

Because the recipient is the delivered@messagebird.dev sandbox address, delivery is guaranteed — the message flows through Bird's real pipeline but never touches a real mailbox.

Next steps

Email API reference — the full request and response schema.
Authentication — keys, scopes, and the Authorization header.
Send your first email — the same flow with the dashboard and SDKs.
Sending domains — verify your own domain for production sending.