Python · FastAPI

Envie seu primeiro e-mail a partir de um endpoint do FastAPI usando o cliente assíncrono do Bird Python SDK. Três passos: instalar, enviar, executar.

1. Instale o SDK

Exemplo de código

python -m pip install messagebird-sdk "fastapi[standard]"

Requer Python 3.10+. O pacote de importação é bird.

2. Envie um e-mail

Exporte sua chave API. O SDK lê BIRD_API_KEY do ambiente e infere a região (us1 ou eu1) a partir do prefixo bk_us1_ / bk_eu1_, então AsyncBird() não precisa de argumentos:

Exemplo de código

export BIRD_API_KEY="bk_us1_..."

Crie main.py. Construa um AsyncBird na inicialização e reutilize-o entre requisições: ele gerencia um pool de conexões e pode ser compartilhado entre tasks com segurança.

Exemplo de código

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_ é a forma Python do campo from (from é uma palavra reservada). onboarding@messagebird.dev é o remetente compartilhado de onboarding do Bird (sem necessidade de verificação de domínio) e delivered@messagebird.dev é um destinatário sandbox que sempre entrega.

O SDK repete automaticamente tentativas em caso de falhas transitórias e reutiliza a chave de idempotência da chamada em cada tentativa. Isso evita que uma nova tentativa envie a mensagem duas vezes.

3. Teste

Exemplo de código

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

Bird aceita a mensagem com um 202 e a entrega de forma assíncrona; seu endpoint retorna o ID em_ e o status:

Exemplo de código

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

Busque a mensagem pelo ID em_ com await client.email.get(...) e acompanhe o status mudar de accepted para delivered.

Próximos passos

Referência de e-mail do Python SDK: todos os métodos e opções.
Envie seu primeiro e-mail: o mesmo fluxo com curl e a lista completa de endereços sandbox.
Domínios de envio: verifique seu próprio domínio para envio em produção.
Referência de e-mail API: o esquema completo de requisição e resposta.

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Assista ao guiaTesting email without spamming anyone Explore a funcionalidadeTest email delivery Siga o percurso de aprendizagemOperate messaging reliably

Experimente na prática e obtenha um resumo de implementação