# 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.

Fonte: https://couryo.com/docs/migration

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:

- [SendGrid](https://couryo.com/docs/migrate-sendgrid.md)
- [Resend](https://couryo.com/docs/migrate-resend.md)
- [Mailgun](https://couryo.com/docs/migrate-mailgun.md)
- [Locaweb](https://couryo.com/docs/migrate-locaweb.md)
- [Qualquer provedor por SMTP](https://couryo.com/docs/migrate-smtp.md)

## 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](https://couryo.com/docs/test-mode.md)).
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](https://couryo.com/docs/domains.md)). Com a Cloudflare conectada, o Couryo cria tudo sozinho. Se o provedor atual já usa o subdomínio `bounces`, veja [o que fazer](https://couryo.com/docs/migrate-smtp.md#dns).
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](https://couryo.com/docs/test-mode.md#link-de-revisao) 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](https://couryo.com/docs/contacts.md#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](https://couryo.com/docs/webhooks.md) 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](https://couryo.com/docs/limits.md#niveis-de-confianca): 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](https://couryo.com/docs/campaigns.md): 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:

```bash title="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](https://couryo.com/docs/errors.md) |
| eventos com nomes próprios | `queued`, `sent`, `delivered`, `deferred`, `bounced`, `complained`, `opened`, `clicked`, `suppressed`, `failed`, `cancelled` ([eventos](https://couryo.com/docs/events.md)) |

## 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](https://couryo.com/docs/sending.md#exportar-em-csv)).