# 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** ([Send your first email](/docs/get-started/send-your-first-email) walks through it), then export it:

```bash
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](/docs/guides/email/testing-sandbox): no domain verification, no real mailbox needed.

```bash
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. The `*_count` fields track your recipients through the delivery states; right now one recipient is accepted and none are delivered:

```json
{
  "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"
}
```

Raw HTTP has no SDK generating 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. [Idempotency](/docs/api/idempotency) has the full semantics.

## 3. Watch it deliver

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

```bash
curl https://us1.platform.bird.com/v1/email/messages/em_01ky7ma8y2es1s2akzk53tmjn0 \
  -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](/docs/api/reference/create-email-message): the full request and response schema.
- [Authentication](/docs/api/authentication): keys, scopes, and the `Authorization` header.
- [Send your first email](/docs/get-started/send-your-first-email): the same flow with the dashboard and SDKs.
- [Sending domains](/docs/guides/email/sending-domains): verify your own domain for production sending.