Pular para o conteúdo
couryo
Páginas do guia

Guia do desenvolvedorMigração

Migrar para o Couryo

Como trocar de provedor de e-mail sem perder entrega nem dados. A ordem segura da migração, o que copiar antes (supressões e contatos), a troca de DNS sem derrubar o envio atual e os guias de SendGrid, Resend, Mailgun, Locaweb e SMTP.

Ver em Markdown

Trocar de provedor de e-mail é seguro quando segue uma ordem: o Couryo entra ao lado do provedor atual, você confere tudo com chaves de teste e só depois move o tráfego, aos poucos. Nada do que o Couryo pede no DNS conflita com os registros do provedor atual, então os dois funcionam ao mesmo tempo durante a transição.

Guias por provedor, com o mapeamento de API e de campos:

A ordem segura#

  1. Crie a conta e uma chave de teste. Em Chaves, crie uma ck_test_ e uma ck_live_ com escopo send. A de teste nunca entrega: serve para validar a integração sem risco (modo de teste).
  2. Cadastre o domínio e publique os registros do Couryo, sem apagar nada do provedor atual. São três: dois CNAMEs de DKIM (couryo1._domainkey e couryo2._domainkey), o CNAME de return path (bounces) e o DMARC, se você ainda não tiver um (domínios e DNS). Com a Cloudflare conectada, o Couryo cria tudo sozinho. Se o provedor atual já usa o subdomínio bounces, veja o que fazer.
  3. Espere o domínio ficar verificado. A página do domínio confere o DNS ao vivo e diz o que falta em cada registro.
  4. Troque o código em homologação com a chave de teste. Os e-mails aparecem em E-mails com o conteúdo e o link de revisão para o time conferir. Os endereços bounced@, complained@ e deferred@ simulam os casos difíceis, com eventos e webhooks de verdade.
  5. Copie as supressões antes do primeiro envio real. Exporte do provedor atual as devoluções permanentes, as reclamações e os descadastros, e cadastre no Couryo (veja abaixo). É o passo que mais protege a sua reputação: mandar de novo para quem já devolveu ou reclamou derruba a entrega no primeiro dia.
  6. Importe os contatos de marketing por CSV, com a confirmação de consentimento (importar por CSV). Endereços suprimidos ficam de fora sozinhos.
  7. Recrie os webhooks no Couryo e ajuste o seu receptor ao formato Standard Webhooks e aos nomes de evento do Couryo (cada guia traz a tabela).
  8. Mova o tráfego aos poucos, começando pelos e-mails mais esperados (login, senha, confirmação de pedido). Uma chave por fluxo ou uma flag no seu código deixa voltar atrás em segundos.
  9. Deixe o provedor antigo ligado por pelo menos 7 dias depois que todo o tráfego passar: e-mails agendados, reenvios e assinaturas DKIM de mensagens ainda em trânsito dependem dele. Depois, apague os registros DNS dele (DKIM e o include: do SPF, se nada mais usar), nunca o MX das suas caixas de e-mail.

Volume e níveis de confiança#

Toda conta nova começa pelos níveis de confiança: com o domínio verificado, o nível 1 envia até 100 por dia e 3 mil por mês; o nível 2 (7 dias limpos e CNPJ conferido ou forma de pagamento) começa em mil por dia e dobra a cada semana limpa; o nível 3 libera o volume do plano. Planeje a migração em etapas a partir disso: mova primeiro o transacional de menor volume e deixe o resto no provedor atual até o nível subir.

Domínio novo para o Couryo, sem histórico de envio, também passa pelo aquecimento: campanhas e sequências de marketing do domínio começam com 50 por dia e dobram a cada dia com envio. O transacional não espera.

Copiar as supressões#

O Couryo não aceita um arquivo de supressões de uma vez: cadastre cada endereço com POST /v1/suppressions (escopo admin). Um laço simples resolve, de um CSV exportado do provedor atual com uma coluna de e-mail:

Supressões de um CSV (uma linha por endereço)
tail -n +2 devolucoes.csv | cut -d, -f1 | while read -r email; do
  curl -s https://api.couryo.com/v1/suppressions \
    -H "Authorization: Bearer $COURYO_ADMIN_KEY" \
    -H "Content-Type: application/json" \
    -d "{ \"email\": \"$email\", \"stream\": \"all\" }" > /dev/null
done
  • Devoluções permanentes e reclamações: stream: "all" (nada sai para esse endereço).
  • Descadastros de marketing: stream: "marketing" (o transacional, como senha e cobrança, continua chegando).
  • Endereço repetido responde 409 already_suppressed, que pode ser ignorado.

O que muda no código#

No provedor atual No Couryo
uma chave de API Authorization: Bearer ck_live_... (produção) ou ck_test_... (teste)
resposta de sucesso sem garantia de fila 202 { id, status } só depois que o e-mail entrou na fila
retentar com medo de duplicar Idempotency-Key em todo POST: a repetição devolve a mesma resposta
erros diferentes por endpoint sempre { error: { type, code, message, param, doc_url, request_id } }, com códigos estáveis
eventos com nomes próprios queued, sent, delivered, deferred, bounced, complained, opened, clicked, suppressed, failed, cancelled (eventos)

Depois da migração#

  • Acompanhe a página Entregabilidade: o agente confere DNS, listas de bloqueio, devoluções e reclamações por provedor e diz o que corrigir.
  • Os relatórios DMARC passam a chegar ao Couryo pelo rua=mailto:reports@dmarc.couryo.com, se você usar o registro sugerido. Com 30 dias limpos, o agente sugere subir o DMARC para p=quarantine.
  • Exporte o log em CSV quando precisar (GET /v1/emails/export, veja exportar em CSV).