Migrar desde SendGrid

Esta guía relaciona los conceptos, las llamadas a la API, los webhooks, las direcciones bloqueadas y las plantillas de SendGrid con sus equivalentes en Emailit. Lee primero Migrar a Emailit para conocer el orden general y cómo usar los dos proveedores en paralelo.

Conceptos

Actualizar las llamadas a la API

POST /v3/mail/send de SendGrid pasa a ser POST /v2/emails. La petición es más plana: no hay personalizations y las direcciones son cadenas simples.

curl https://api.sendgrid.com/v3/mail/send \
  -H "Authorization: Bearer $SENDGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "personalizations": [{ "to": [{ "email": "ada@example.com" }] }],
    "from": { "email": "hello@acme.com", "name": "Acme" },
    "subject": "Your receipt",
    "content": [
      { "type": "text/plain", "value": "Thanks for your order." },
      { "type": "text/html", "value": "<p>Thanks for your order.</p>" }
    ]
  }'

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "subject": "Your receipt",
    "text": "Thanks for your order.",
    "html": "<p>Thanks for your order.</p>"
  }'

Cada destinatario de una petición a Emailit se convierte en un email independiente con su propio ID. Para enviar variables distintas a personas distintas, que SendGrid hace con varios personalizations, envía una petición por destinatario. Añade una cabecera Idempotency-Key para que los reintentos sean seguros. Consulta Enviar un email.

Cambiar la configuración SMTP

Emailit no lee la cabecera X-SMTPAPI. Elimínala y configura el seguimiento en el dominio. Consulta Configuración SMTP.

Equivalencias de los eventos de webhook

Igual que SendGrid, Emailit envía por POST un array JSON de eventos. Los campos son distintos:

• El nombre del evento está en type y el email, en data.object. Usa data.object.id (el ID em_ de la respuesta de envío) en lugar de sg_message_id, y data.object.to en lugar de email.
• Tus valores de meta vuelven en data.object.meta.
• Emailit firma las peticiones con HMAC-SHA256 en lugar de con la clave pública ECDSA de SendGrid. Verifica X-Emailit-Signature con tu secreto whsec_. Consulta Verificar las firmas de los webhooks.

for (const event of req.body) {
  const email = event.data.object;
  if (event.type === 'email.bounced') markBounced(email.to, email.id);
  if (event.type === 'email.complained') unsubscribe(email.to);
}

Trasladar las direcciones bloqueadas

1. En SendGrid, exporta tus Bounces, Spam Reports, Invalid Emails y Global Unsubscribes, desde las páginas de Suppressions o con los endpoints /v3/suppression/* de la API. Los Blocks suelen ser temporales, así que puedes omitirlos.

2. Crea un único CSV con las columnas email,type,reason:

   CSV

   email,type,reason
   old-address@example.com,recipient,sendgrid bounce
   angry@example.com,recipient,sendgrid spam report

   Usa el tipo recipient para las direcciones que nunca deben recibir emails. Bloquea los envíos por API, por SMTP y de campañas. Los tipos bounce, complaint y unsubscribe solo detienen las campañas.

3. En Email API›Suppressions, selecciona Import y sube el archivo. Cada archivo puede tener hasta 10.000 filas y ocupar como máximo 8 MB, así que divide las listas más grandes. Los duplicados se omiten.

Para las bajas de grupos del email de marketing, importa a esas personas como contactos con unsubscribed activado, en lugar de bloquearlas para todos los emails. Consulta Gestionar las direcciones bloqueadas.

Trasladar las plantillas

Exporta el HTML de cada plantilla dinámica de SendGrid y después impórtalo en Email Marketing›Templates o crea la plantilla con la API de plantillas. Asigna a cada plantilla un alias, como receipt, y envíala con "template": "receipt".

Las dos usan dobles llaves, pero Temple es más reducido que Handlebars:

Consulta Lenguaje de plantillas Temple e Importar, exportar y duplicar plantillas.

Cambiar los DNS

Añade tu dominio en Email API›Domains y publica los registros de Emailit. Usan sus propios nombres (emailit._domainkey, emailit.<domain> y, opcionalmente, go e inbound), así que no entran en conflicto con los CNAME de domain authentication ni de link branding de SendGrid. Conserva tu registro DMARC. Después del cambio definitivo, elimina los CNAME de SendGrid. Consulta Registros DNS de los dominios de envío.

Si usabas Inbound Parse, haz que el registro MX de tu nombre de host de parse apunte a Emailit. Para conservar el mismo nombre de host, como parse.acme.com, establece el inbound_key del dominio en parse con la API. Consulta Configurar el email entrante.

Próximos pasos

• Lista de comprobación para pasar a producción
• Configurar un webhook
• Migración prioritaria: deja que los ingenieros de Emailit hagan la migración contigo