Python · FastAPI

Send your first email from a FastAPI endpoint using the Bird Python SDK's async client. Three steps: install, send, run.

1. Install the SDK

Codebeispiel

pip install messagebird-sdk "fastapi[standard]"

Codebeispiel

# or
uv add messagebird-sdk "fastapi[standard]"
poetry add messagebird-sdk "fastapi[standard]"

Requires Python 3.10+. The import package is bird.

2. Send an email

Export your API key. The SDK reads BIRD_API_KEY from the environment and infers the region (us1 or eu1) from the bk_us1_ / bk_eu1_ prefix, so AsyncBird() needs no arguments:

Codebeispiel

export BIRD_API_KEY="bk_us1_..."

Create main.py. Construct one AsyncBird at startup and reuse it across requests: it pools connections and is safe to share across tasks.

Codebeispiel

from bird import AsyncBird, APIError
from fastapi import FastAPI, HTTPException

app = FastAPI()
client = AsyncBird()


@app.post("/send", status_code=202)
async def send() -> dict[str, str]:
    try:
        message = await client.email.send(
            from_="onboarding@messagebird.dev",
            to=["delivered@messagebird.dev"],
            subject="Hello from Bird",
            html="<p>My first Bird email.</p>",
        )
    except APIError as err:
        raise HTTPException(status_code=502, detail=str(err))
    return {"id": message.id, "status": message.status}

from_ is the Python spelling of the from field (from is a reserved word). onboarding@messagebird.dev is Bird's shared onboarding sender (no domain verification needed) and delivered@messagebird.dev is a sandbox recipient that always delivers.

Transient failures retry automatically, and a retried send reuses one idempotency key across attempts, so it never double-applies.

3. Try it

Codebeispiel

fastapi dev main.py
curl -X POST http://localhost:8000/send

Bird accepts the message with a 202 and delivers it asynchronously; your endpoint returns the em_ ID and status:

Codebeispiel

{
  "id": "em_01ky7ma8y2es1s2akzk53tmjn0",
  "status": "accepted"
}

Fetch the message by its em_ ID with await client.email.get(...) and watch the status move from accepted to delivered.

Next steps

Python SDK email reference: every method and option.
Send your first email: the same flow with curl and the full sandbox address list.
Sending domains: verify your own domain for production sending.
Email API reference: the full request and response schema.