O SendGrid e o Couryo fazem a mesma coisa com formatos diferentes: no SendGrid um envio carrega personalizations; no Couryo cada e-mail é um objeto simples, e vários vão juntos no lote. Siga a ordem segura da migração e use este guia para traduzir cada parte.

A chamada de envio#

SendGrid: POST https://api.sendgrid.com/v3/mail/send

curl https://api.sendgrid.com/v3/mail/send \
  -H "Authorization: Bearer $SENDGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "personalizations": [{ "to": [{ "email": "ana@exemplo.com.br", "name": "Ana" }] }],
    "from": { "email": "pedidos@exemplo.com.br", "name": "Loja" },
    "subject": "Pedido 1042 confirmado",
    "content": [
      { "type": "text/plain", "value": "Obrigado, Ana!" },
      { "type": "text/html", "value": "<p>Obrigado, Ana!</p>" }
    ],
    "categories": ["pedido"],
    "custom_args": { "pedido_id": "1042" }
  }'

Couryo: POST https://api.couryo.com/v1/emails

curl https://api.couryo.com/v1/emails \
  -H "Authorization: Bearer $COURYO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1042-confirmacao" \
  -d '{
    "from": "Loja <pedidos@exemplo.com.br>",
    "to": "Ana <ana@exemplo.com.br>",
    "subject": "Pedido 1042 confirmado",
    "text": "Obrigado, Ana!",
    "html": "<p>Obrigado, Ana!</p>",
    "tags": { "categoria": "pedido" },
    "metadata": { "pedido_id": "1042" }
  }'

O SendGrid responde 202 sem corpo e com o cabeçalho X-Message-Id. O Couryo responde 202 { "id": "msg_...", "status": "queued" }, só depois de o e-mail entrar na fila.

Campos#

SendGrid	Couryo	Observação
`from: { email, name }`	`from: "Nome <email>"`	texto, num domínio verificado
`personalizations[].to/cc/bcc`	`to`, `cc`, `bcc` (texto ou lista)	até 50 destinatários por e-mail; cada personalização vira um item do lote
`reply_to` / `reply_to_list`	`reply_to`
`subject`	`subject`
`content` (`text/plain`, `text/html`)	`text`, `html`	mande os dois: a parte em texto ajuda a entrega
`template_id` + `dynamic_template_data`	`template` + `variables`	o template precisa existir no Couryo (veja abaixo)
`attachments[]` (`content`, `filename`, `type`, `content_id`)	`attachments[]` (`content`, `filename`, `content_type`, `content_id`)	Base64, até 20
`headers`	`headers`	cabeçalhos da plataforma (`From`, `Message-ID`, `List-Unsubscribe`...) são ignorados
`categories`	`tags`	chave e valor, por exemplo `{ "categoria": "pedido" }`
`custom_args`	`metadata`	volta em todo webhook
`send_at` (Unix, até 72 h)	`scheduled_at` (ISO 8601, até 30 dias)	dá para reagendar e cancelar pelo id do e-mail
`batch_id` + cancelar agendados	`POST /v1/emails/{id}/cancel`	um por e-mail
`asm.group_id` (grupos de descadastro)	`stream: "marketing"` + tópicos	o descadastro em um clique entra sozinho no marketing
`tracking_settings`	rastreio do projeto	ligado no marketing, desligado no transacional por padrão
`mail_settings.sandbox_mode`	chave `ck_test_`	captura sem entregar, com eventos simulados

Templates dinâmicos#

Os templates do SendGrid usam Handlebars. No Couryo, as variáveis são {{nome}} e {{pedido.total}}, com valor padrão opcional ({{nome|cliente}}); blocos como {{#if}} e {{#each}} não existem. Recrie cada template em Templates (HTML, MJML ou o editor visual) e mande template com o nome ou o id:

Corpo com template

{ "from": "Loja <pedidos@exemplo.com.br>", "to": "ana@exemplo.com.br", "template": "pedido-confirmado", "variables": { "nome": "Ana", "pedido": { "numero": "1042" } } }

Lista de produtos e partes condicionais: monte o trecho em HTML no seu código e passe como variável, ou use um template por caso.

Eventos do Event Webhook#

SendGrid	Couryo
`processed`	`accepted` e `queued`
`delivered`	`delivered`
`deferred`	`deferred`
`bounce` (e `blocked`)	`bounced`
`dropped`	`suppressed` (endereço suprimido) ou `failed` (barrado antes do envio)
`spamreport`	`complained`
`open`	`opened` (com `machine: true` quando foi o programa de e-mail, não a pessoa)
`click`	`clicked` (com a `url`)
`unsubscribe`, `group_unsubscribe`	não vira evento: o endereço entra na supressão de marketing (`GET /v1/suppressions?reason=unsubscribe`)

O Event Webhook manda vários eventos num array e assina com ECDSA. O Couryo manda um evento por chamada, no padrão Standard Webhooks (HMAC-SHA256 com os cabeçalhos webhook-id, webhook-timestamp e webhook-signature), com novas tentativas por até 3 dias.

Supressões e contatos#

Exporte do SendGrid (Suppressions) as listas Bounces, Spam Reports, Invalid Emails e Blocks permanentes, e cadastre no Couryo com stream: "all". Unsubscribes e Group Unsubscribes entram com stream: "marketing". O laço está em copiar as supressões.
Contatos do Marketing Campaigns: exporte em CSV e importe no Couryo, com a confirmação de consentimento. Listas viram tags ou tópicos.

SMTP#

Se você usa o relay do SendGrid (smtp.sendgrid.net, usuário apikey), troque só as credenciais: servidor smtp.couryo.com, porta 587, usuário couryo e a chave do Couryo como senha. O cabeçalho X-SMTPAPI não existe no Couryo: use X-Couryo-Tags e X-Couryo-Stream (SMTP).

DNS#

O SendGrid usa registros próprios (os CNAMEs em…, s1._domainkey e s2._domainkey, e os de link branding). Eles não conflitam com os do Couryo (couryo1._domainkey, couryo2._domainkey e bounces), então os dois ficam publicados juntos durante a migração.

Publique os registros do Couryo e espere o domínio ficar verificado.
Mantenha o DMARC que você já tem: o Couryo respeita o seu registro. Para receber os relatórios no agente de entregabilidade, acrescente mailto:reports@dmarc.couryo.com ao rua.
Depois que todo o tráfego estiver no Couryo e se passarem 7 dias, apague os CNAMEs do SendGrid. Não mexa no MX nem no SPF das suas caixas de e-mail.

Migrar do SendGrid