# Migre este projeto do Resend para o Ritto Mail Você está migrando uma aplicação do Resend para o Ritto Mail. A API REST do Ritto Mail é compatível no wire com a do Resend — mesmos endpoints, mesmos formatos de requisição e resposta — então isto é uma mudança de configuração mais uma migração dos dados da conta, não uma reescrita. Siga os passos na ordem. Pare e pergunte antes de qualquer ação irreversível. Nunca imprima, registre em log ou commite uma chave de API. ## Fatos em que você pode confiar - URL base da API: `https://api.ritto.email`. Painel: https://app.ritto.email. - Chaves de API começam com `rm_` (chaves criadas antes da mudança de nome começam com `ms_` e continuam funcionando) e são criadas no painel em **Chaves de API**. Use uma chave de acesso total para a migração e chaves de acesso de envio para os remetentes de produção. - Documentação: https://docs.ritto.email — acrescente `.md` à URL de qualquer página para obter markdown, `/llms-full.txt` é tudo em um arquivo, `/openapi.json` é a especificação OpenAPI 3.1. O guia de migração está em https://docs.ritto.email/pt-BR/migrate-from-resend.md e a referência da CLI em https://docs.ritto.email/pt-BR/cli.md. - A CLI de migração (pacote npm `ritto-mail`) só lê do Resend (requisições `GET`), mantém as chaves em memória, não as grava em arquivo algum e não envia telemetria. - Os ids diferem entre os provedores: contatos são casados por e-mail, o restante por nome, chave, alias ou endpoint. O relatório da CLI traz um mapa de ids para tópicos e segmentos. ## Passo 1 — Inventário desta base de código Encontre todo ponto de contato com o Resend antes de mudar qualquer coisa e mostre a lista ao usuário: - Pacotes de SDK: `resend` (Node), `resend` (Python), `resend-go`, `resend-php`, `resend-ruby`, `resend-java`, `resend-dotnet`, `resend-elixir`. - Variáveis de ambiente: `RESEND_API_KEY`, `RESEND_BASE_URL` e qualquer `https://api.resend.com` fixo no código. - Receptores de webhook que verificam os cabeçalhos de assinatura `svix-*`, e as URLs de endpoint registradas no Resend. - Ids ou aliases de audiências, segmentos, tópicos e templates referenciados em código ou configuração. - Corpos de broadcast ou template que usam `{{{RESEND_UNSUBSCRIBE_URL}}}` (continua funcionando no Ritto Mail como alias de `{{{UNSUBSCRIBE_URL}}}`). ## Passo 2 — Mova a conta Peça ao usuário uma chave do Resend com acesso total, e uma chave do Ritto Mail com acesso total (criada no painel em https://app.ritto.email). Passe as chaves por variáveis de ambiente, nunca como argumentos de linha de comando. Primeiro o plano (somente leitura; código de saída 2 significa que há mudanças, 0 nada a fazer, 1 erro): ```sh export RESEND_API_KEY=re_... export RITTO_MAIL_API_KEY=rm_... npx ritto-mail migrate plan --from resend --out plan.json ``` Mostre ao usuário o resumo do plano, incluindo avisos de limite do plano (por exemplo "7 domínios a criar; o plano Starter permite 3"), e aguarde a aprovação. Então aplique: ```sh npx ritto-mail migrate apply plan.json --yes ``` Flags que valem conhecer: `--rps ` reduz a taxa de leitura contra o Resend (padrão 8; o Resend permite 10 por time, compartilhados com o envio em produção); `--skip enrichment` pula a segunda passagem por contato para propriedades e tópicos; `--include-sent` importa também broadcasts enviados como rascunhos; `--fresh-webhook-secrets` gera novos segredos de webhook em vez de copiá-los; `--on-conflict skip|error` muda como contatos já existentes são tratados (padrão upsert). Depois leia `.ritto-mail/migrate-report.md`: contagens por recurso, o checklist de itens manuais, os registros DNS por domínio e o mapa de ids. A ferramenta acrescenta `.ritto-mail/` ao `.gitignore` quando existe um; confirme que fez isso. ## Passo 3 — Aponte o código para o Ritto Mail Mantenha o SDK do Resend — o Ritto Mail não tem SDKs próprios, e os SDKs oficiais do Resend funcionam com ele sem mudanças. Defina, em todo ambiente que envia: ```sh RESEND_API_KEY=rm_... RESEND_BASE_URL=https://api.ritto.email ``` Confirme que o SDK instalado lê `RESEND_BASE_URL` e substitua qualquer `https://api.resend.com` fixo no código. A variável precisa estar no ambiente do processo antes de o SDK ser importado: o `resend` de Node até a 6.12.3 a lê uma vez, ao carregar o módulo, e ignora a opção `baseUrl` no construtor (suportada a partir da 6.12.4), então nunca a atribua no código depois do import — confira a versão com `npm ls resend`. Um `401` "API key is invalid" com uma chave `rm_` significa que o pedido ainda foi para o Resend. Exceções: o SDK de Python lê `RESEND_API_URL` (ou `resend.api_url`); o de Ruby precisa da barra final (`RESEND_BASE_URL=https://api.ritto.email/`); em Go, definir `client.BaseURL` funciona em todas as versões; os SDKs de Java (`Resend.builder().baseUrl(...)`), .NET (`ResendClientOptions.ApiUrl`) e Elixir (`base_url` na config de `Resend.Client`) recebem a URL base como opção do cliente. Detalhes por linguagem: https://docs.ritto.email/pt-BR/sdks.md. Então resolva o que o relatório lista: - Atualize ids de tópicos e segmentos em código e configuração usando o mapa de ids do relatório. - Templates: templates do Ritto Mail não armazenam `from` nem `reply_to`; passe-os em cada envio. - Webhooks: endpoint, eventos e segredo de assinatura foram copiados, então o receptor existente continua verificando os cabeçalhos `svix-*`. Tipos de evento fora dos sete tipos `email.*` do Ritto Mail foram descartados por webhook e estão listados; remova ou substitua os handlers deles. - Chaves de API não podem ser migradas (o Resend expõe apenas os nomes). Crie uma para cada nome que o relatório lista, no painel, e coloque-as nos ambientes correspondentes. ## Passo 4 — DNS, feito pelo usuário O Ritto Mail usa seu próprio par de chaves DKIM, então todo domínio precisa de novos registros DNS mesmo que já envie pelo Resend. Os registros estão no relatório e em **Domínios** no painel. Os dois provedores podem ficar verificados lado a lado. Não mude o tráfego até cada domínio aparecer como **Verificado**. ## Passo 5 — Faça a virada e verifique 1. Rode `migrate plan` e `migrate apply` de novo logo antes de virar o tráfego: cada execução é um diff, então os contatos que chegaram nesse meio-tempo vêm junto e nada é duplicado. 2. Faça o deploy das mudanças de ambiente do passo 3. 3. Envie um e-mail pela nova URL base e confirme que ele chega a **Entregue** na página de E-mails; confirme que uma entrega de webhook chega ao receptor. 4. Mantenha a conta do Resend intocada até o usuário estar confiante. Se algo precisar ser desfeito do lado do Ritto Mail, `npx ritto-mail migrate rollback` apaga somente o que a ferramenta criou, depois de listar e perguntar. ## Regras - O Resend é somente leitura durante toda a migração: nunca crie, altere ou apague nada lá. - Chaves passam por variáveis de ambiente ou stdin, nunca por arquivos, logs, argumentos ou commits. - Pergunte antes de aplicar o plano, antes de mexer em variáveis de ambiente de produção e antes de qualquer mudança de DNS. - Termine com um resumo: o que mudou no repositório, o que foi movido na conta e exatamente os itens que o usuário ainda precisa fazer.