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. Para este guia, você não precisa verificar um domínio de envio nem publicar registros DNS. Verifique seu próprio domínio antes de enviar para clientes.

1. Crie uma chave API

No dashboard, acesse Platform tools > API keys e crie uma chave. As chaves pertencem a uma região e têm o formato bk_us1_... ou bk_eu1_.... A região no prefixo indica qual host API você deve chamar: https://us1.platform.bird.com ou https://eu1.platform.bird.com.

A página API Keys no dashboard da Bird, com a lista de chaves, o prefixo mascarado, os escopos e o horário do último uso de cada uma

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 da etapa 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, que já está disponível no seu espaço de trabalho sem nenhuma configuração. Endereçe a mensagem para delivered@messagebird.dev, um destinatário de sandbox que sempre recebe a entrega. Assim, o resultado é previsível sem uma caixa de correio real.

A chamada cURL usa o host dos EUA. Se a sua chave começar com bk_eu1_, chame https://eu1.platform.bird.com. O SDK lê a região da sua chave e seleciona o host. A aba TypeScript exige 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 ver as etapas completas de instalação e execução em cada linguagem ou framework, consulte os quickstarts de SDK.

3. Veja o resultado

A API responde com 202: a Bird aceitou o envio para processamento assíncrono. Verifique o status de entrega separadamente. Os campos *_count acompanham os destinatários pelos estados de entrega. Na resposta inicial, um destinatário consta como aceito e nenhum como 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 ID em_ para ver o estado atual dela. Uma mensagem passa de accepted por processed até delivered. Consulte repetidamente até que a mensagem do sandbox chegue a delivered:

const msg = await bird.email.get("em_abc123");
msg.status; // "accepted" | "processed" | "delivered" | "bounced" | …
msg.delivered_count;
msg.bounced_count;
console.log(msg.subject, msg.subject_recipient_id);

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 registro de data e hora delivered_at. Consulte o guia de eventos para saber o que delivered comprova 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 correio real. Para testar uma devolução, envie para bounce@messagebird.dev. O guia do sandbox de testes lista todos os endereços do sandbox e o resultado simulado de cada um.

Sobre o domínio de integração

O remetente compartilhado onboarding@messagebird.dev está disponível para a integração inicial e tem estes limites:

  • Além dos endereços do 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 todos os endereços em to, cc e bcc, incluindo os destinatários do sandbox. Acima desse 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 próprio endereço em from; todo o resto da solicitação continua igual.

Próximos passos