Guía de migración
Migrar de SendGrid a Mail.Land
A menudo el cambio se reduce a un host SMTP o a una llamada a la API. Esta guía asigna los campos habituales de SendGrid a Mail.Land y enumera las diferencias que requieren un cambio en el código.
# Before (SendGrid)
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASS=<your SendGrid API key>
# After (Mail.Land)
SMTP_HOST=smtp.mail.land
SMTP_PORT=587 # STARTTLS
SMTP_USER=apikey # any value; Mail.Land ignores it
SMTP_PASS=<your Mail.Land API key with SMTP enabled>Conceptos de SendGrid en Mail.Land
| SendGrid | Mail.Land |
|---|---|
| Clave de API (API key) | Clave de API (credencial), limitada a la API o a SMTP, a dominios y a direcciones IP |
| Autenticación del remitente (Sender authentication) | Verificación del dominio (SPF, DKIM, DMARC y return path) |
| Plantillas dinámicas (Dynamic templates) | Plantillas con marcadores {{name}} |
| Supresiones y grupos de baja (unsubscribe groups) | Supresiones con un ámbito: todo el correo, solo marketing o una lista de correo concreta |
| Event Webhook | Webhooks firmados con HMAC-SHA256 |
| Inbound Parse | Rutas de entrada |
Cambiar SMTP: modifique tres ajustes
Si envía a través de SMTP, cambie el host, el puerto y la contraseña. El nombre de usuario puede seguir siendo apikey, porque Mail.Land lo ignora y autentica solo con la clave.
| Ajuste | SendGrid | Mail.Land |
|---|---|---|
| Host | smtp.sendgrid.net | smtp.mail.land |
| Puerto | 25, 587 o 2525 (TLS), o 465 (SSL) | 587 con STARTTLS |
| Nombre de usuario | apikey | Cualquier valor, por ejemplo apikey |
| Contraseña | Su clave de API de SendGrid | Una clave de API de Mail.Land con SMTP habilitado |
Mail.Land solo acepta el inicio de sesión después de STARTTLS, y no ofrece el puerto 465. Si su aplicación utiliza el puerto 465, cámbiela al 587 con STARTTLS.
Cambiar la llamada a la API
La llamada de envío de Mail.Land utiliza un cuerpo JSON más plano y la cabecera X-API-Key. Este es el mismo mensaje en ambas API.
curl -X POST https://api.sendgrid.com/v3/mail/send \
-H "Authorization: Bearer $SENDGRID_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"personalizations": [{
"to": [{ "email": "[email protected]", "name": "Jane" }],
"dynamic_template_data": { "orderNumber": "12345" }
}],
"from": { "email": "[email protected]", "name": "Your Shop" },
"reply_to": { "email": "[email protected]" },
"subject": "Order 12345 has shipped",
"content": [
{ "type": "text/plain", "value": "Your order is on its way." },
{ "type": "text/html", "value": "<p>Your order is on its way.</p>" }
],
"categories": ["order-shipped"]
}'curl -X POST https://api.mail.land/v1/transactional/send \
-H "X-API-Key: $MAILLAND_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": [{
"email": "[email protected]", "name": "Jane",
"variables": { "orderNumber": "12345" }
}],
"from": { "email": "[email protected]", "name": "Your Shop" },
"replyTo": "[email protected]",
"subject": "Order 12345 has shipped",
"textContent": "Your order is on its way.",
"htmlContent": "<p>Your order is on its way.</p>",
"tags": ["order-shipped"]
}'Correspondencia de campos de la llamada de envío
De POST /v3/mail/send a POST /v1/transactional/send.
| SendGrid | Mail.Land | Nota |
|---|---|---|
Authorization: Bearer <key> | X-API-Key: <key> | Una cabecera distinta. |
from.email, from.name | from.email, from.name | La dirección debe pertenecer a un dominio verificado. |
personalizations[].to[] | to[] | Hasta 5 destinatarios por solicitud con una clave transaccional. Para envíos masivos, utilice el envío por lotes con una clave de marketing. |
personalizations[].cc, bcc | Ninguno | No se admite. Envíe un mensaje independiente a cada destinatario. |
personalizations[].dynamic_template_data | to[].variables | Valores por destinatario. Utilice variables en el nivel superior para los valores comunes a todos los destinatarios. |
subject | subject | Obligatorio salvo que utilice una plantilla. |
content[] (text/html) | htmlContent | |
content[] (text/plain) | textContent | |
template_id | templateId | Vuelva a crear antes la plantilla en Mail.Land; el ID cambia. |
reply_to.email | replyTo | Una cadena con la dirección, sin más. |
categories, custom_args | tags | Las etiquetas aparecen en la analítica y en los eventos de webhook. |
headers | customHeaders | |
attachments[].content, filename, type | attachments[].content, fileName, contentType | Contenido en Base64. Hasta 10 archivos adjuntos y 10 MiB en total. |
attachments[].disposition, content_id | attachments[].inline, contentId | inline: true para una imagen insertada. |
send_at (hora Unix, hasta 72 horas de antelación) | scheduledAt (fecha y hora UTC, hasta 7 días de antelación) | |
tracking_settings (open, click) | tracking.opens, tracking.clicks | Para las aperturas, prevalece la configuración de seguimiento propia del dominio. |
asm.group_id | Ninguno en la llamada de envío | Las bajas de marketing se gestionan con las listas y campañas de Mail.Land. Importe las bajas de grupo existentes; consulte más abajo. |
Sin equivalente | Cabecera X-Idempotency-Key | Dentro del periodo de conservación, un reintento con la misma clave devuelve la respuesta original en lugar de volver a enviar. |
Ambas API responden 202 Accepted. El cuerpo de la respuesta de Mail.Land incluye un jobId, un ID de mensaje por destinatario y las listas de destinatarios aceptados y rechazados.
Importe primero sus listas de supresión
Impórtelas antes de su primer envío a través de Mail.Land, para que las personas que se dieron de baja o presentaron una queja sigan suprimidas desde el principio. Exporte cada lista de SendGrid en CSV y, después, impórtela con el tipo y el ámbito correspondientes, en el panel de control o con POST /v1/transactional/suppressions/import.
| Lista de SendGrid | Tipo en Mail.Land | Ámbito |
|---|---|---|
| Rebotes (Bounces) | HardBounce | Global |
| Denuncias de spam (Spam reports) | Complaint | Global |
| Correos no válidos (Invalid emails) | Invalid | Global |
| Bajas globales (Global unsubscribes) | Unsubscribe | Global |
| Bajas de grupo (Group unsubscribes) | Unsubscribe | List, para la lista de correo de Mail.Land correspondiente; Marketing bloquea todo el correo de marketing |
Los bloqueos (blocks) de SendGrid suelen ser rechazos temporales. Revíselos antes de importarlos en lugar de suprimirlos todos.
Dirija sus webhooks a Mail.Land
Añada su endpoint en Mail.Land, elija los eventos y verifique la cabecera X-MLND-Signature con el secreto de su webhook. Los nombres de los eventos difieren de los de SendGrid, así que actualice su controlador:
| Evento de SendGrid | Evento de Mail.Land |
|---|---|
delivered | message.delivered |
deferred | message.deferred |
bounce | message.bounced |
open, click | Aún no disponible |
spamreport | message.complained |
unsubscribe | message.unsubscribed |
Elimine duplicados según el campo event_id: una entrega reintentada lleva el mismo ID de evento. Los eventos open y click de SendGrid no tienen hoy un webhook equivalente en Mail.Land: los eventos de apertura y clic están catalogados, pero no se envían.
Haga el cambio paso a paso
- Añada y verifique su dominio de envío en Mail.Land. Conserve sus registros de SendGrid: añada include:spf.mlnd.net a su registro SPF existente en lugar de crear uno segundo, y mantenga un único registro DMARC.
- Importe sus listas de supresión.
- Cree una clave de sandbox configurada en modo solo registro y ejecute sus pruebas de integración contra Mail.Land sin entregar correo.
- Envíe mensajes reales a direcciones que usted controle y compruébelos en el registro de correo.
- Traslade una aplicación o una pequeña parte del tráfico y, después, supervise la entrega, los rebotes y las quejas.
- Mientras funcionen ambos proveedores, copie a Mail.Land las nuevas bajas, quejas y rebotes de SendGrid, y haga una sincronización final antes de cambiar el último tráfico.
- Traslade el resto y mantenga SendGrid activo hasta que hayan salido sus últimos mensajes programados y reintentados.
Preguntas frecuentes
¿Puedo seguir enviando a través de SendGrid mientras hago pruebas?
Sí. Verificar un dominio en Mail.Land no impide que SendGrid siga enviando para él, así que puede utilizar ambos y trasladar el tráfico de forma gradual.
¿Admite Mail.Land cc y bcc?
No en la llamada de envío. En su lugar, envíe un mensaje independiente a cada destinatario.
¿Existe un SDK oficial de Mail.Land?
Todavía no. La documentación incluye ejemplos listos para copiar y pegar de la API REST en ocho lenguajes, y cualquier biblioteca SMTP funciona con el relé.
¿Qué ocurre con mis grupos de baja?
Importe las bajas de cada grupo con el ámbito List para la lista de correo de Mail.Land correspondiente, y envíe a esa lista para que se aplique la preferencia. El ámbito Marketing es la alternativa más amplia: bloquea todo el correo de marketing a esa dirección.
¿Listo para dejar SendGrid?
Cree una cuenta gratuita y envíe hoy mismo su primera prueba. Si desea ayuda, cuéntenos cómo está configurado su sistema.