Sign inGet Started

Envie seu primeiro e-mail

Crie uma chave API, envie pelo domínio de onboarding compartilhado da Bird e confira o resultado. Você não precisa verificar um domínio de envio nem publicar registros DNS para este guia. Verifique seu próprio domínio antes de enviar para clientes.

1. Crie uma chave API

No dashboard, acesse Developers > Chaves API e crie uma chave. As chaves são vinculadas a uma região e têm o formato bk_us1_... ou bk_eu1_...; a região no prefixo indica qual host API chamar: https://us1.platform.bird.com ou https://eu1.platform.bird.com.
Página de chaves API no dashboard da Bird, listando chaves com prefixo mascarado, escopos e último uso
A chave completa é exibida uma única vez, no momento da criação. Copie-a para um lugar seguro e depois exporte-a para que os trechos de código do passo 2 possam lê-la:
Exemplo de código
export BIRD_API_KEY="bk_us1_..."

2. Envie um e-mail

Envie a partir de onboarding@messagebird.dev, o domínio de onboarding compartilhado da Bird, disponível no seu espaço de trabalho sem nenhuma configuração. Enderece para delivered@messagebird.dev, um destinatário de sandbox que sempre entrega, para que o resultado seja determinístico sem uma caixa de e-mail real.
A chamada cURL usa o host dos EUA. Se sua chave começa com bk_eu1_, chame https://eu1.platform.bird.com em vez disso. O SDK lê a região da sua chave e seleciona o host. A aba TypeScript requer npm install @messagebird/sdk.
import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

const msg = await bird.email.send({
  from: { email: "onboarding@messagebird.dev", name: "Bird" },
  to: ["delivered@messagebird.dev"],
  subject: "Hello from Bird",
  html: "<p>My first Bird email.</p>",
});

console.log(msg.id, msg.status);
Para instruções completas de instalação e execução em cada linguagem ou framework, use os quickstarts por SDK.

3. Veja o resultado

A API responde com 202: Bird aceitou o envio para processamento assíncrono. Verifique o status de entrega separadamente. Os campos *_count rastreiam os destinatários ao longo dos estados de entrega. Na resposta inicial, um destinatário está aceito e nenhum está entregue.
Exemplo de código
{
  "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"
}
Busque a mensagem pelo em_ ID para ver seu estado atual. Uma mensagem passa de accepted por processed até delivered. Faça polling até a mensagem de sandbox alcançar delivered:
const msg = await bird.email.get("em_abc123");
msg.status; // "accepted" | "processed" | "delivered" | "bounced" | …
msg.delivered_count;
msg.bounced_count;
Na aba cURL, substitua {region} e {message_id}, e use $BIRD_API_KEY no lugar de $TOKEN.
A leitura agora mostra status: "delivered", delivered_count: 1 e um timestamp delivered_at. Consulte o guia de eventos para saber o que delivered estabelece para um destinatário real.
Como você enviou para delivered@messagebird.dev, o resultado é garantido: a mensagem passa pelo pipeline de entrega real da Bird, incluindo os formatos de eventos e webhooks de produção, mas nunca chega a uma caixa de e-mail real. Para testar um bounce, envie para bounce@messagebird.dev. O guia do sandbox de testes lista todos os endereços de sandbox e seus resultados simulados.

Sobre o domínio de onboarding

O remetente compartilhado onboarding@messagebird.dev está disponível para onboarding e tem estes limites:
  • Fora os endereços de sandbox @messagebird.dev, ele só entrega para membros verificados do seu espaço de trabalho; qualquer outro destinatário é rejeitado com um 422.
  • Os envios são limitados a 50 destinatários por organização por dia UTC, contando cada endereço to, cc e bcc, incluindo destinatários de sandbox. Acima do limite, a API retorna um 429.
Quando estiver pronto para enviar e-mails a clientes reais, verifique seu próprio domínio de envio e coloque seu endereço em from; todo o resto da solicitação permanece igual.

Próximos passos