Documentação
Sign inGet started
Começar
Guias
Referência de API
SDKs
CLI
Base de conhecimento
Changelog

Migrar de outro provedor

Use este guia para migrar e-mail de produção de outro provedor. Mapeie a solicitação de envio, publique registros DNS, importe supressões, traduza eventos de webhook e teste a integração antes de direcionar o tráfego de produção para Bird.
Checklist de migração:
  1. Mapeie sua chamada de envio para POST /v1/email/messages
  2. Redirecione seus domínios de envio e DNS
  3. Importe sua lista de supressão
  4. Adapte webhooks para nosso vocabulário de eventos
  5. Verifique no sandbox de e-mail antes da virada
As etapas 1, 3 e 4 dependem do provedor que você está deixando. Seu guia do provedor contém o mapeamento campo a campo do payload, onde exportar sua lista de supressão e a tabela de tradução de nomes de eventos de webhook.

1. Mapear a chamada de envio

Temos um único endpoint de envio, POST /v1/email/messages. Você monta um payload JSON plano (sem wrapper personalizations, sem montagem MIME) com from, arrays to/cc/bcc, subject, html e/ou text, uma lista opcional reply_to e headers para cabeçalhos de e-mail personalizados. Um envio bem-sucedido retorna 202 Accepted com um ID de mensagem prefixado por em_. Os resultados de entrega chegam de forma assíncrona por webhooks e pelos endpoints de leitura. O payload completo, com todos os limites e valores padrão de cada campo, está em Envio de e-mail. O mapeamento campo a campo do seu payload atual está no seu guia do provedor. Se sua aplicação envia por SMTP hoje, talvez você nem precise portar a chamada: nós aceitamos envio via SMTP no mesmo pipeline, o que transforma esta etapa em uma troca de credenciais.
Use tags como dimensões de filtro em listas de mensagens, analytics e rollups do dashboard. Use metadata para contexto estruturado que Bird armazena na mensagem, retorna em leituras de API e repassa em eventos de webhook. Veja Tags vs metadata para os limites.
Antes de portar o código, leve em conta estas diferenças:
  • Agendamento, templates armazenados e anexos migram normalmente. Use scheduled_at para envio agendado. Use template em vez de conteúdo inline para templates armazenados. Mapeie os arquivos para o array attachments.
  • Destinatários suprimidos são rejeitados de forma visível. Um endereço suprimido ainda recebe um recipient_id e aparece na lista de destinatários da mensagem com status rejected e um evento email.rejected (rejection_reason: recipient_suppressed), nunca como uma exclusão silenciosa. Mesmo quando todos os destinatários estão suprimidos, a solicitação ainda é aceita com um 202. Cada destinatário retorna como rejeitado. Veja Supressões.
  • Defina category: "transactional" para e-mail operacional. Um envio assume por padrão marketing, e a categoria controla a política de supressão: marketing bloqueia em caso de reclamações e cancelamentos de assinatura, transactional entrega mesmo assim. Newsletters e campanhas são tratadas corretamente pelo valor padrão. Marque recibos, redefinições de senha e e-mails operacionais similares como transactional para que não sejam bloqueados por um cancelamento de assinatura.

2. Redirecionar domínios e DNS

Registre cada domínio de envio com POST /v1/email/domains ou em Email > Domains, depois publique os registros de dns_records. DKIM, o CNAME de return-path e uma política DMARC liberam o envio. Um registro DMARC existente, inclusive em um domínio pai, é suficiente. O CNAME de tracking libera apenas o rastreamento de abertura e clique com sua marca. Domínios de envio cobre os registros, o ciclo de verificação e o modelo regional. Use o divisor de registro DNS se o seu provedor exigir um valor DKIM dividido, e o gerador de política DMARC se você precisar de uma política.
Um registro que a maioria dos provedores pede logo de início está deliberadamente ausente: você não publica nenhum registro SPF no apex do seu domínio. SPF é avaliado contra o domínio do envelope-from, que o CNAME de return-path aponta para nós, então SPF passa e alinha sem tocar no seu apex. Se o seu provedor antigo fez você adicionar um include: ao registro SPF do seu apex, mantenha-o durante a transição e remova-o após a virada. Ele não ajuda nem prejudica e-mails enviados por nós, e removê-lo libera uma das 10 consultas DNS que o SPF do apex permite. A explicação completa está em DKIM, SPF & DMARC.
Você pode publicar nossos registros enquanto os registros do seu provedor antigo ainda estiverem ativos. O registro DKIM usa um seletor nosso. Os CNAMEs de return-path e tracking são novos hostnames que você escolhe, e seu registro DMARC existente satisfaz o requisito sem alterações. Ambos os provedores autenticam lado a lado até você estar pronto para migrar o tráfego. O estado do domínio é regional, então registre o domínio em cada região de onde você envia.

3. Importar supressões

Transfira sua lista de supressão antes de enviar tráfego de produção por nós. Caso contrário, seus primeiros envios vão para endereços que já deram bounce ou geraram reclamação no seu provedor antigo, o que prejudica a reputação que você está tentando proteger.
Exporte a lista do seu provedor atual (seu guia do provedor tem os endpoints exatos), depois adicione cada endereço aqui com POST /v1/email/suppressions:
Exemplo de código
while read -r address; do
  curl -s -X POST https://us1.platform.bird.com/v1/email/suppressions \
    -H "Authorization: Bearer $BIRD_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"email\": \"$address\"}"
done < suppressions.txt
Duas coisas sobre esse caminho de importação:
  • Você importa um endereço por solicitação. O API de supressões é CRUD de entrada única, então uma lista grande significa iterar sobre os endereços exportados. A chamada é idempotente (201 para um registro novo, 200 com o registro existente se o endereço já estiver suprimido manualmente), então reexecutar uma importação parcial é seguro.
  • Endereços importados recebem reason: manual, applies_to: all, o que bloqueia todas as categorias, incluindo transacional. Isso é mais restritivo que um registro nativo de reclamação, que bloqueia apenas envios não transacionais. Se você precisar do comportamento por categoria para endereços específicos, veja a taxonomia de motivos em Supressões.
A partir de agora, você não gerencia bounces por conta própria: nós suprimimos automaticamente hard bounces e reclamações, disparando email_suppression.created para que seus sistemas espelhem a lista de supressão. Cancelamentos de assinatura são registrados como preferência declarada e espelhados via email.unsubscribed e email.list_unsubscribed, não pelo evento de supressão.

4. Adaptar webhooks

Registre um endpoint com POST /v1/webhooks e inscreva-o em uma lista explícita de tipos de evento. Nossos nomes de evento seguem resource.action: email.accepted → email.processed → email.delivered no caminho feliz, com email.deferred, email.bounced, email.complained, email.rejected, email.opened, email.clicked e o par de cancelamento de assinatura cobrindo o restante. A tradução de nomes de evento do vocabulário do seu provedor atual está no seu guia do provedor. Os schemas de payload por evento estão na referência de eventos.
A correlação migra sem problemas. Cada evento tem os identificadores email_id, recipient_id e workspace_id. Ele também repassa tags e metadata da solicitação de envio. Isso retorna o contexto que seu provedor antigo devolvia via echo de payload, sem uma consulta extra. Coloque seus IDs internos em metadata no envio e leia-os diretamente em cada evento.
Nós assinamos as entregas conforme a especificação Standard Webhooks, usando três cabeçalhos: webhook-id, webhook-timestamp e webhook-signature, com um HMAC-SHA256 sobre {id}.{timestamp}.{raw body}. Se você já verifica entregas Standard Webhooks de outra plataforma, o mesmo código de verificação funciona aqui. Caso contrário, a receita de verificação, o cronograma de retentativas e as ferramentas de replay estão em Webhooks & events. As entregas são at-least-once e não ordenadas, então deduplicar por webhook-id e ordenar pelo timestamp do payload é a mesma disciplina que seu handler atual já deve ter.

5. Verificar no sandbox antes da virada

Antes de migrar o tráfego de produção, execute sua integração completa (a chamada de envio portada, seu handler de webhook, seu espelhamento de supressão) contra o sandbox de e-mail. Envios no sandbox vão para endereços mágicos em messagebird.dev e passam pelo pipeline de produção real: mesmo 202, mesma sequência de eventos, mesmas entregas de webhook assinadas, sem nunca chegar a uma caixa de entrada ou afetar sua reputação.
Um smoke test mínimo pré-virada:
  1. Envie para delivered@messagebird.dev e confirme que seu handler processa email.accepted → email.processed → email.delivered.
  2. Envie para bounce@messagebird.dev e confirme que seu tratamento de bounce dispara em email.bounced (bounces simulados não gravam na sua lista de supressão, então o endereço continua reutilizável).
  3. Envie para suppressed@messagebird.dev e confirme que você trata email.accepted seguido de email.rejected, sem email.processed nem eventos de entrega depois. Esse é o formato que todo destinatário suprimido produz em produção; o detalhe rejection_reason: recipient_suppressed está no registro do destinatário e nos eventos API.
  4. Envie uma mensagem category: "marketing" e confirme que a categoria aparece onde você espera na leitura da mensagem.
Use subendereçamento +label (bounce+cutover-test@messagebird.dev) para correlacionar casos de teste. O endereço completo aparece nos seus eventos. Quando o smoke test passar, migre o tráfego. Aponte sua aplicação para nós e mantenha o DNS do provedor antigo até que seus domínios aqui mostrem capabilities.sending verificado. Acompanhe as primeiras horas de entregas reais no dashboard e no seu stream de webhooks.

Migrando de um provedor específico

  • SendGrid: personalizations → payload plano, categories/custom_args → tags/metadata, a equivalência dropped ↔ email.rejected
  • Mailgun: parâmetros o:*/v:*/h:* → campos nativos, exportação de bounces/complaints/unsubscribes
  • Amazon SES: SendEmail v2 → um endpoint, configuration sets → flags de rastreamento por mensagem, SNS → webhooks assinados
  • Resend: formato de payload quase idêntico, webhooks assinados por Svix → Standard Webhooks
  • Postmark: destinatários separados por vírgula → arrays, dumps de supressão por stream, webhooks não assinados → assinados
  • Brevo: objetos de endereço → endereços simples, duas blocklists separadas para exportar, params → template.parameters
  • MailerSend: cinco listas de supressão das quais a temporária fica para trás, personalization → parâmetros por envio
  • Mailjet: o array Messages → um payload plano, EventPayload → metadata, exportação de blocklist
  • Mandrill: o wrapper message e autenticação no body → payload plano e autenticação bearer, exportação da rejection blacklist

Próximos passos

  • Envio de e-mail: o payload completo de envio, tags vs metadata, o modelo assíncrono 202
  • Domínios de envio: registro, ciclo de verificação, configuração multirregião
  • DKIM, SPF & DMARC: o que cada registro prova e por que SPF no apex não é necessário
  • Supressões: motivos, categorias e o API de gerenciamento
  • Webhooks & events: configuração de endpoint, verificação Standard Webhooks, retentativas e replay
  • Events: schemas de payload por evento
  • Sandbox de teste: a lista completa de endereços mágicos e tutoriais
  • Referência API: schemas de solicitação e resposta para o endpoint de envio

Recursos relacionados

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

Assista ao guiaGetting started with emailExplore a funcionalidadeEmailSiga o percurso de aprendizagemBuild your first integrationGuia de implementaçãoSend your first email
Experimente na prática e obtenha um resumo de implementação