Migrar do SparkPost

Use este guia para mover o envio de e-mails do SparkPost para o Bird. Siga o checklist principal de migração, usando os mapeamentos abaixo para sua integração HTTP ou SMTP.

Antes de começar

Você precisa de acesso à sua conta e subcontas do SparkPost, DNS do domínio de envio, configuração da aplicação e handler de webhook. Prepare um espaço de trabalho Bird e uma chave API na região escolhida. A importação de opt-out também requer permissão de escrita preferences na chave.

Faça o inventário de remetentes, templates, snippets, listas de destinatários, supressões, envios agendados, pools de IP e webhooks. Inclua SDKs, adaptadores de e-mail de frameworks, jobs em segundo plano e fluxos de e-mail de entrada. Registre os novos IDs de recursos à medida que os cria; IDs e credenciais do SparkPost não funcionam no Bird. Use os SDKs Bird ao substituir um cliente SparkPost, e revise seus retries, timeouts e paginação.

Se você usa subcontas do SparkPost, fale conosco antes de escolher o layout do espaço de trabalho. Confirme os espaços de trabalho disponíveis, permissões, recursos compartilhados e o fluxo de provisionamento de tenants. Uma chave API de espaço de trabalho não pode alternar tenants com X-MSYS-SUBACCOUNT. Preserve tenants suspensos e restrições de envio específicas de tenant durante a migração.

Confirme que as franquias do plano e os limites de requisições do Bird cobrem seu volume de envio, quantidade de recursos e picos de tráfego.

Registre seus domínios de envio com antecedência. Preserve o DNS funcional do SparkPost e escolha hostnames separados de return-path e tracking quando necessário. Se o registro reportar um conflito de propriedade, entre em contato com o suporte antes de remover um domínio ativo.

IPs dedicados: fale conosco ou com sua equipe de conta antes de migrar. Peça para confirmarmos se seus IPs existentes do SparkPost podem ser movidos para o Bird e combine a configuração do pool, o cronograma e qualquer aquecimento necessário. Inclua a região da sua conta, endereços IP, nomes dos pools e volume de envio. Mantenha seus IPs atuais ativos até que o plano de migração seja confirmado.

Confirme a seleção de pool e as allowlists de IP ou hostname dos destinatários antes do cutover. Comprar um IP não altera o pool padrão. IPs recém-adquiridos podem enviar excedente pela infraestrutura compartilhada durante o aquecimento, o que importa se os destinatários aceitam e-mails apenas de IPs específicos.

Entregue isto ao seu agente

Cole isto no seu agente de codificação no repositório da sua aplicação:

Help me migrate my SparkPost email integration to Bird.
1. Use an existing Bird MCP connection or signed-in CLI. Otherwise follow https://bird.com/docs/ai/set-up-your-agent.md. Append .md to Bird docs URLs to read Markdown.
2. Read https://bird.com/docs/guides/email/migrate/sparkpost.md and https://bird.com/docs/guides/email/migrate.md. Make a read-only inventory of my SparkPost call sites, SDKs, resource IDs, configured URLs, sending domains, and scheduled jobs before editing. Never print API keys.
3. Propose workspace and region mappings. If subaccounts, dedicated IPs, or domain ownership conflicts need a migration plan, use the available Bird tools to open a human email support ticket and return its ID. For CLI usage, read https://bird.com/docs/cli/reference/support-tickets-create.md. Wait for the agreed plan before moving those resources.
4. Follow https://bird.com/docs/guides/email/sending-domains.md; preserve working DNS and show me proposed records. Ask before DNS changes or paid provisioning.
5. Port sending, templates, and webhooks using this guide. Preserve recipient privacy, personalization, and categories. Export suppressions with scope and type; show me the handling before importing or changing preferences.
6. Test using https://bird.com/docs/guides/email/testing-sandbox.md. Show me results and unresolved differences, including tracking, signatures, and correlation.
7. Ask for explicit approval before production cutover. Keep a rollback path; get separate approval before retiring SparkPost resources or credentials.

Mapeie a chamada de envio

Substitua POST /api/v1/transmissions por POST /v1/email/messages, ou POST /v1/email/batches para mensagens independentes. A visão geral de API do SparkPost lista seus hosts regionais e autenticação. Bird usa https://us1.platform.bird.com ou https://eu1.platform.bird.com, correspondendo à região da sua chave API, com Authorization: Bearer $BIRD_API_KEY.

Uma transmissão do SparkPost pode gerar e-mails separados e personalizados para seus destinatários. Bird compartilha conteúdo e parâmetros entre os destinatários de um envio. Use uma mensagem separada para cada personalização, opcionalmente agrupada em um lote. Envios somente para To permanecem endereçados individualmente; verifique os cabeçalhos visíveis ao adicionar cópias Cc/Bcc.

Mapeie os campos de transmissão do SparkPost:

Para cópias To/Cc/Bcc de um mesmo e-mail, reconstrua o grupo de destinatários uma vez. Os endereços exibidos do SparkPost podem diferir dos destinatários de entrega; to, cc e bcc do Bird adicionam destinatários de entrega cada um. Copiar um cabeçalho CC do SparkPost no cc de cada mensagem expandida pode enviar cópias duplicadas. Verifique os cabeçalhos visíveis e a contagem de destinatários antes de migrar.

Verifique os limites de campos de envio, o agendamento e as regras de anexo. Atualize os IDs de imagens inline e as referências cid: correspondentes para atender às regras do Bird. Configure o return path e o domínio de rastreamento no domínio.

Os campos de envio HTTP do Bird não incluem content.email_rfc822, content.amp_html ou options.inline_css do SparkPost. Reconstrua mensagens brutas com os campos suportados, forneça fallbacks HTML/texto para AMP e aplique CSS inline antes de enviar HTML. O SMTP analisa e reconstrói as partes suportadas da mensagem; valide o MIME recebido se você depende da estrutura exata. Parâmetros MIME de anexo, como method de calendário ou charset de texto, não são preservados.

Para mensagens API agendadas, o Bird fixa a versão do template, o idioma e os parâmetros ao aceitar a solicitação. Edições posteriores no template não atualizam essa mensagem. Para alterá-la, cancele a mensagem agendada antes do início do processamento e envie uma substituição. Mantenha um grupo de IDs de mensagem Bird se precisar substituir o cancelamento baseado em campanha do SparkPost.

Defina BIRD_API_KEY com a sua chave Bird. Este exemplo de sandbox não exige domínio verificado e não alcança nenhuma caixa de entrada real. Para uma chave EU, use https://eu1.platform.bird.com:

curl --fail-with-body https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "onboarding@messagebird.dev",
    "to": ["delivered@messagebird.dev"],
    "subject": "Your receipt",
    "text": "Thanks for your order, {{ first_name }}.",
    "parameters": {"first_name": "Alex"},
    "category": "transactional",
    "metadata": {"order_id": "order_123"},
    "tags": [{"name": "mailstream", "value": "receipts"}]
  }'

Espere 202 Accepted e um ID de mensagem em_. Armazene esse ID e acompanhe os resultados por destinatário através de eventos. Aceitação não garante entrega: um destinatário suprimido pode ser aceito e depois rejeitado. Atualize o parsing da resposta, o tratamento de erros e as tentativas idempotentes junto com a chamada de envio.

Para um lote, leia o array data e salve o ID de cada mensagem associado ao seu próprio registro de envio. Bird valida o lote antes de enfileirar: uma única mensagem inválida pode rejeitar toda a solicitação. Divida transmissões grandes para caber nos limites de lote e siga as regras de nova tentativa de Bird quando a resposta for ambígua.

Atribua a cada solicitação distinta ou fragmento de lote sua própria chave de idempotência estável. A janela de repetição de Bird difere da do SparkPost; mantenha os registros de envio da sua aplicação além dessa janela para evitar duplicatas durante a migração ou rollback.

Migre remetentes SMTP

Use as configurações de conexão SMTP de Bird, o nome de usuário bird e uma chave API com envio de e-mail habilitado. Verifique a região, TLS e a configuração da chave.

Converta as opções X-MSYS-API do SparkPost antes de remover o cabeçalho. Defina os padrões de categoria, tags, rastreamento e pool na configuração SMTP de Bird. Essas configurações se aplicam por chave API; use chaves configuradas separadas ou HTTP quando variarem entre mensagens. Use HTTP para metadados por mensagem ou parâmetros de template.

Coloque cada destinatário de entrega no envelope SMTP, os destinatários visíveis nos cabeçalhos MIME To/Cc, e os destinatários Bcc apenas no envelope. Inventarie X-MSYS-API.archive separadamente: cópias de arquivo do SparkPost preservam as URLs de rastreamento do destinatário original, então Bcc comum não é equivalente. Valide uma substituição antes de trocar esse fluxo.

Copie suas configurações de rastreamento efetivas explicitamente: a chave SMTP não configurada de Bird habilita rastreamento de abertura e clique, enquanto os padrões do SparkPost variam por conta. Defina a categoria também: Bird SMTP usa transacional como padrão e HTTP inline usa marketing. Remetentes de newsletter precisam de marketing em ambos os caminhos.

Para novas tentativas SMTP, reutilize a chave de idempotência, o envelope e os bytes MIME exatos. Regenerar Date, Message-ID ou limites MIME altera o payload e pode impedir uma nova tentativa segura.

Converta templates

Exporte as versões que você realmente envia pela API de Templates API do SparkPost: liste com GET /api/v1/templates?draft=false e recupere o conteúdo com GET /api/v1/templates/{id}?draft=false. Salve rascunhos separadamente se necessário. Inclua templates compartilhados com subcontas e snippets referenciados no inventário.

A linguagem de template do SparkPost e a sintaxe Liquid de Bird são diferentes. Converta condicionais, loops, valores padrão e valores aninhados. Resolva substituições de destinatário e metadados usados na renderização em parâmetros explícitos. Por exemplo, {{ if ... }} se torna {% if ... %}. A sintaxe {{ name }} compartilhada por si só não garante compatibilidade.

Expanda snippets antes de publicar; o Liquid de Bird não suporta include ou render. Para templates armazenados, substitua referências externas como {{ user.name }} por parâmetros planos como {{ user_name }}. Se você insere HTML dinâmico por meio de parâmetros do SparkPost, renderize-o na sua aplicação e envie o corpo completo sem parameters inline; valores de parâmetros HTML comuns são escapados.

Crie, visualize e publique um template Bird e depois siga enviando com um template. Leve o remetente efetivo, Reply-To e cabeçalhos personalizados do SparkPost para a solicitação de envio; os templates Bird fornecem o conteúdo.

Para Liquid inline, inclua parameters, mesmo {}; omiti-lo deixa os tokens inalterados. Verifique valores ausentes, escaping e URLs.

Substitua os placeholders de cancelamento de inscrição por {{ bird.unsubscribe_url }}. Bird fornece cabeçalhos de cancelamento de inscrição para marketing; remova os cabeçalhos personalizados List-Unsubscribe e List-Unsubscribe-Post dos envios de marketing para evitar uma rejeição 422.

Os links de cancelamento de inscrição de Bird removem o endereço do e-mail de marketing em todo o espaço de trabalho. Esses links não oferecem cancelamentos específicos por lista. Verifique esse comportamento se a sua integração com o SparkPost oferece assinaturas separadas.

Migrar listas de destinatários

Exporte cada lista de destinatários armazenada com GET /api/v1/recipient-lists/{id}?show_recipients=true para incluir associação e personalização. Crie as audiências de destino e registre as propriedades de contato antes de importar. Revise cada resultado de importação e reconcilie as contagens de associação.

As propriedades de contato pertencem ao contato em todas as suas audiências. Se o mesmo endereço tem dados de substituição diferentes em várias listas do SparkPost, reconcilie esses valores antes de importar para evitar sobrescrevê-los. As propriedades de contato de Bird têm tipos escalares; mantenha a personalização específica por lista ou estruturada na sua aplicação quando ela não puder ser representada com segurança.

Use broadcasts quando um template publicado puder ser preenchido a partir de propriedades de contato. A associação à audiência é resolvida quando o envio começa, e os limites de envio e concorrência de broadcast se aplicam. Use mensagens em lote independentes para parâmetros específicos da solicitação ou um snapshot fixo de destinatários. Valide o consentimento e o tratamento de supressões antes de ativar uma lista migrada.

Exportar supressões

Exporte antes do envio em produção. Comece com GET /api/v1/suppression-list?cursor=initial&types=transactional,non_transactional,open_tracking e depois siga a paginação até o final. Salve os registros completos, incluindo tipo, origem, ID da lista, subconta e timestamps. Use X-MSYS-SUBACCOUNT: 0 para a conta principal e o ID de cada subconta para a respectiva lista. Consulte a Suppression List API do SparkPost.

Classifique os registros por tipo, origem e escopo antes de usar o loop de importação do guia principal. O POST /v1/email/suppressions de Bird recebe um email e cria um bloqueio manual em todo o espaço de trabalho para ambas as categorias:

• Endereços bloqueados para recebimento de e-mail: importe aqueles que devem ser bloqueados em todas as categorias. Preserve a exportação original para reconciliação; os registros importados levam o motivo manual de Bird.
• Opt-outs de marketing em toda a conta: use POST /v1/preferences com channel: "email", o endereço em handle, status: "revoked" e coverage: "non_transactional". Defina source: "sparkpost-migration" para reconciliação. Revise as preferências Bird existentes antes e preserve restrições mais rígidas; inspecione applied e a preferência retornada após cada gravação.
• Restrições específicas de lista ou somente transacionais: preserve o escopo delas na elegibilidade de envio da sua aplicação. As preferências de e-mail de Bird são válidas para todo o canal e não conseguem representar esses escopos. Uma supressão manual também pode bloquear redefinições de senha. Mantenha o tráfego afetado pausado até verificar a substituição.
• Opt-outs de rastreamento de abertura: defina track_opens: false para a mensagem independente, além de quaisquer restrições de envio. Para SMTP, use uma chave com rastreamento de abertura desabilitado ou use HTTP para controle por mensagem.

A solicitação de preferência acima registra a restrição no momento da importação. Mantenha os timestamps originais do SparkPost na sua exportação e reconcilie qualquer consentimento posterior antes de gravar. Reconcilie registros importados e gravações com falha e, em seguida, teste ambas as categorias. Sincronize novos opt-outs e supressões enquanto ambos os provedores enviam. Continue aplicando opt-outs de e-mails anteriormente entregues pelo SparkPost em Bird após a migração. Consulte Supressões para o tratamento nativo de bounces e reclamações.

Converta eventos de webhook

O SparkPost envia eventos de webhook em lote dentro de wrappers msys. Bird entrega um evento por solicitação com type, timestamp e data. Registre um endpoint Bird com assinaturas de eventos explícitas e verificação de assinatura. Mantenha o handler do SparkPost ativo para o tráfego restante.

Envios diretos via API e SMTP emitem email.accepted antes do processamento. Broadcasts registram a aceitação nos eventos API e no log de e-mail, mas omitem esse webhook. Os eventos policy_rejection, generation_failure e generation_rejection do SparkPost correspondem a email.rejected; inspecione rejection_reason. Deduplique aberturas separadamente ao contabilizar engajamento único.

Use data.email_id e data.recipient_id para correlação de Bird, e inclua seus próprios identificadores em metadata. Substitua o tratamento de batch ID do SparkPost pelas regras de deduplicação e ordenação de webhooks do Bird. Leia os detalhes do bounce antes de decidir se um endereço deve ser suprimido; a classificação de bounce distingue falhas permanentes de endereço de falhas temporárias ou de política.

Preserve o histórico de relatórios

Exporte o histórico de eventos do SparkPost e os relatórios agregados de que você precisa antes que suas janelas de retenção expirem. Siga a paginação de eventos até o final e preserve IDs de provedor, escopo de conta/subconta, timestamps e filtros de relatório. Continue coletando eventos atrasados durante a sobreposição e mantenha o histórico do SparkPost em um arquivo separado.

Salve uma linha de base para cada fluxo de envio. Compare populações de destinatários e janelas de relatório correspondentes, e verifique as definições de métricas: aceitação pelo provedor, entrega no servidor do destinatário, engajamento único e aberturas pré-carregadas são medidas diferentes. Nomes de métricas iguais, por si só, não garantem taxas comparáveis.

Migre e-mail de entrada separadamente

Se você usa relay webhooks do SparkPost, siga Recebendo e-mail para esse fluxo. O webhook email.received do Bird fornece um inbound_message_id; busque o corpo, os anexos ou o MIME bruto pela API em vez de esperar a mensagem completa no webhook. Teste seu handler com um endereço de encaminhamento Bird, depois prepare o recebimento de domínio antes de alterar os registros MX. Verifique o roteamento de respostas após a alteração de DNS e arquive o conteúdo necessário além do período de retenção de recebimento do Bird.

Verifique e faça a transição

1. Verifique a capacidade de envio de cada domínio. Execute o teste de fumaça no sandbox e os casos de reclamação. Confirme que os eventos assinados chegam ao seu handler, correspondem à mensagem correta e lidam com entregas duplicadas. Eventos de sandbox não comprovam entrega na caixa de entrada, renderização ou rastreamento.
2. Envie a partir do seu domínio verificado para caixas de entrada reais controladas. Verifique personalização, visibilidade de To/Cc/Bcc, anexos, autenticação e rastreamento. Teste um cancelamento de inscrição: o marketing deve parar enquanto e-mails transacionais elegíveis continuam. Teste separadamente se bloqueios de todas as categorias rejeitam ambos. Mantenha essas verificações distintas dos resultados simulados no sandbox.
3. Atribua envios agendados pendentes a um único provedor. Drene ou cancele o original antes de recriá-lo em outro lugar. Mantenha um registro na aplicação de qual provedor aceitou cada envio lógico para que tentativas de reenvio ou rollback não enviem uma segunda cópia.
4. Migre uma parcela controlada do tráfego e monitore as métricas de entrega e o processamento de webhooks. Para IPs dedicados, siga o plano de migração combinado com nossa equipe, incluindo qualquer aquecimento. Aumente o tráfego após os resultados observados atenderem aos seus requisitos de entrega.
5. Se a validação falhar, pause o tráfego afetado do Bird e roteie novos envios pelo caminho do SparkPost mantido, com os opt-outs atuais aplicados. Reconcilie envios ambíguos antes de tentar novamente. Desative credenciais, webhooks e DNS antigos após as filas e eventos atrasados serem contabilizados; mantenha os links de rastreamento e cancelamento de inscrição antigos funcionais para e-mails já entregues.

Se a autenticação falhar, verifique o bearer token e a região do Bird. Se as importações de preferência retornarem 403, verifique a permissão de escrita preferences da chave antes de continuar. Se a personalização renderizar incorretamente, inspecione a conversão Liquid e os parâmetros. Se e-mails transacionais forem rejeitados inesperadamente, verifique as supressões manuais importadas. Use o log de e-mail e os detalhes de eventos para verificar cada correção.

Próximos passos

• Enviando e-mail: campos do payload, personalização e resultados assíncronos
• Templates de e-mail: pré-visualização, publicação e suporte a Liquid
• Supressões: motivos de supressão e gerenciamento
• Webhooks e eventos: assinaturas, novas tentativas e replay