Twilio SendGrid: Guía técnica completa para email transaccional

⚡Resumen

• 📢 SendGrid utiliza un Return-Path personalizable (subdominio de tu dominio), permitiendo la alineación SPF en modo relaxed para DMARC desde el plan base.
• La Web API v3 es el método recomendado: 10 000 peticiones/segundo, hasta 1 000 destinatarios por llamada, Dynamic Templates con Handlebars.
• Domain Authentication con Automated Security genera 3 CNAME: Return-Path + 2 selectores DKIM (rotación automática, claves 2048 bits).
• IP dedicada recomendada a partir de 50 000 emails/mes, con warm-up automático de 41 días y coste de 30$/mes por IP adicional.
• Plan Free eliminado en mayo de 2025: migración obligatoria a Essentials 50K a 19,95$/mes mínimo.

Introducción

SendGrid se ha consolidado como una de las plataformas de email transaccional más robustas del mercado, procesando más de 190 mil millones de emails mensuales en 2024. Adquirido por Twilio en 2019 por aproximadamente 3 mil millones de dólares, el servicio combina una potente API REST, un relé SMTP universal y funcionalidades de autenticación avanzadas que lo distinguen de la competencia.

La fortaleza de SendGrid reside en tres pilares técnicos principales: una Web API v3 capaz de gestionar 10 000 peticiones/segundo, una Domain Authentication que permite la alineación SPF DMARC desde el plan base, y un sistema de rotación automática de claves DKIM 2048 bits sin interrupción del servicio.

Esta guía está dirigida a desarrolladores, DevOps y arquitectos de sistemas que buscan integrar SendGrid para email transaccional con una comprensión completa de la infraestructura: configuración DNS, elección API vs SMTP, gestión de IP dedicadas, límites técnicos y webhooks de eventos.

Web API v3 vs SMTP Relay: arquitectura y elección de integración

SendGrid propone dos métodos de integración para email transaccional, ambos disponibles desde los planes de pago.

Comparativa técnica

Criterio	Web API v3	SMTP Relay
Endpoint	POST https://api.sendgrid.com/v3/mail/send	smtp.sendgrid.net puertos 587/465
Autenticación	Bearer token (API key)	User: apikey / Pass: API key
Rate limit	10 000 peticiones/segundo	Depende de la IP y el plan
Destinatarios/req	Hasta 1 000 (personalizations)	1 email = 1 conexión SMTP
Templates	Dynamic Templates (Handlebars)	Contenido inline únicamente
Scheduling	send_at (hasta 72h por adelantado)	Vía header X-SMTPAPI
Tracking	Nativo (click, open, Google Analytics)	Vía X-SMTPAPI
Compatibilidad	Requiere SDK o cliente HTTP	Cualquier sistema compatible con SMTP
Caso de uso ideal	Apps modernas, batch, personalización avanzada	Legacy, plugins CMS, servidores mail

¿Cuándo elegir Web API v3?

La Web API v3 es el método recomendado por SendGrid para cualquier nueva integración. Es accesible en POST https://api.sendgrid.com/v3/mail/send (o api.eu.sendgrid.com para la región EU).

Ventajas clave:

• Personalizations: envío de hasta 1 000 destinatarios en una sola petición, cada uno recibiendo contenido personalizado diferente
• Dynamic Templates: sintaxis Handlebars con condiciones, bucles, comparaciones, formato de fechas
• Scheduling: programación de envío hasta 72 horas por adelantado con posibilidad de cancelación
• Rate limit generoso: 10 000 peticiones/segundo en el endpoint mail/send

Ejemplo de envío con personalización:

{
  "personalizations": [{
    "to": [{"email": "usuario@captaindns.com", "name": "Juan García"}],
    "dynamic_template_data": {
      "nombre": "Juan",
      "numero_pedido": "ORD-12345",
      "importe": "149,90 €"
    }
  }],
  "from": {"email": "pedidos@captaindns.com"},
  "template_id": "d-abc123def456"
}

SDKs oficiales: SendGrid mantiene 7 SDKs oficiales (Node.js, Python, PHP, Ruby, Go, Java, C#) que encapsulan la API REST y simplifican la integración.

¿Cuándo elegir SMTP Relay?

El SMTP Relay es ideal para sistemas legacy o aplicaciones que solo soportan SMTP.

Configuración oficial:

SMTP server: smtp.sendgrid.net
SMTP user: apikey (literalmente la cadena "apikey")
SMTP password: [tu clave API SendGrid]
Port: 587 (TLS recomendado) o 465 (SSL) o 2525 (fallback)

Punto crítico: la autenticación SMTP utiliza una configuración específica. El nombre de usuario es literalmente la cadena apikey (no tu identificador de cuenta), y la contraseña es tu clave API SendGrid.

Header X-SMTPAPI: permite acceder a funcionalidades avanzadas vía SMTP (categories, unique_args, filtros, scheduling, tags de sustitución). Tamaño máximo: 10 000 bytes.

Ejemplo de header X-SMTPAPI para tracking:

{
  "category": ["confirmacion_pedido"],
  "unique_args": {
    "order_id": "ORD-12345",
    "customer_id": "CUST-789"
  },
  "filters": {
    "clicktrack": {"settings": {"enable": 1}},
    "opentrack": {"settings": {"enable": 1}}
  }
}

Domain Authentication: SPF, DKIM 2048 bits y alineación DMARC

La autenticación de dominio en SendGrid genera los registros DNS necesarios para SPF, DKIM y la alineación DMARC. El proceso se efectúa en Settings > Sender Authentication > Domain Authentication.

Arquitectura con Automated Security (recomendado)

Con la opción Automated Security activada, SendGrid genera 3 registros CNAME:

1. CNAME para Return-Path: em1234.captaindns.com apuntando a SendGrid
2. CNAME DKIM s1: s1._domainkey.captaindns.com → s1.domainkey.u1234.wl5678.sendgrid.net
3. CNAME DKIM s2: s2._domainkey.captaindns.com → s2.domainkey.u1234.wl5678.sendgrid.net

Ventajas de esta arquitectura:

• Rotación automática de claves DKIM: los dos selectores (s1 y s2) permiten a SendGrid cambiar las claves sin interrupción del servicio
• Claves DKIM 2048 bits por defecto desde mayo de 2021 (configuraciones anteriores pueden usar 1024 bits)
• Ningún registro SPF manual requerido: el CNAME delega la gestión SPF a SendGrid
• Selectores personalizables: 1-3 caracteres alfanuméricos en los parámetros avanzados

Return-Path y alineación SPF: una ventaja importante

El Return-Path (Envelope From) es crucial para la alineación DMARC. Por defecto, SendGrid utiliza un subdominio en formato em[XXX].captaindns.com:

• SPF pasa automáticamente porque el CNAME delega la gestión SPF a SendGrid
• La alineación SPF funciona en modo relaxed (el subdominio em1234.captaindns.com corresponde al dominio padre captaindns.com)
• No es necesario modificar tu SPF principal: el CNAME gestiona todo

Sin embargo, para una política DMARC estricta (aspf=s), la alineación SPF fallará porque el dominio Return-Path nunca coincidirá exactamente con el dominio From. La solución es apoyarse en DKIM para la alineación DMARC, que soporta el modo estricto (adkim=s).

Custom Return Path

La opción Custom Return Path en los parámetros avanzados permite personalizar el subdominio (por ejemplo mail.captaindns.com en lugar de em1234.captaindns.com).

Link Branding

El Link Branding reemplaza los dominios SendGrid en los enlaces rastreados por tu propio dominio. En lugar de sendgrid.net/click/xxx, los enlaces mostrarán url1234.captaindns.com/click/xxx. Esta configuración requiere 2 registros CNAME adicionales y mejora la confianza de los destinatarios.

Migración a DKIM 2048 bits

Para migrar una configuración anterior (claves 1024 bits) hacia 2048 bits, hay que crear una nueva autenticación de dominio con un nuevo selector personalizado no utilizado anteriormente.

IP dedicada vs IP compartida: estrategia de entregabilidad

SendGrid recomienda oficialmente una IP dedicada a partir de 50 000 emails al mes. Más allá de 200 000-300 000 emails mensuales, se aconsejan dos IP dedicadas.

IP compartida (planes Free y Essentials)

Ventajas:

• Ningún warm-up necesario
• Reputación mantenida por SendGrid
• Ideal para volúmenes bajos o irregulares

Inconvenientes:

• Exposición a riesgos de reputación relacionados con otros remitentes del pool
• Problemas de blocklist frecuentes en Microsoft/Outlook

IP dedicada (plan Pro y superior)

El plan Pro incluye 1 IP dedicada, con posibilidad de añadir a 30$/mes por IP adicional.

Ventajas:

• Reputación aislada y controlable
• Función de IP Warmup automático durante 41 días
• Posibilidad de separar flujos (transaccional vs marketing)

IP Warmup automático: limita progresivamente los envíos según un calendario predefinido:

• Día 1: 20 emails/hora
• Día 41: Más de 19 millones/hora

IP Pools: permiten agrupar varias IP dedicadas y asignarlas a diferentes flujos. La separación se refuerza con los Subusers (subcuentas aisladas con sus propias estadísticas, listas de supresión y webhooks).

Subusers: los planes Pro y Premier soportan hasta 15 subusers por cuenta.

¿Cuándo elegir una IP dedicada?

Necesitas una IP dedicada si:

• Volumen regular > 50 000 emails/mes
• Necesidad de separar reputación transaccional vs marketing
• Requisitos de whitelisting de cliente o cumplimiento normativo
• Volumen > 200 000 emails/mes: 2 IP dedicadas recomendadas

Permanece en IP compartida si:

• Volumen < 50 000 emails/mes
• Envíos irregulares o esporádicos
• Inicio de actividad sin historial

Tarifas 2025 y evolución del plan Free

Planes Email API

Plan	Volumen mensual	Precio/mes	IP dedicada	Subusers
Free	100/día (60d)	Gratis	No	No
Essentials 50K	50 000	19,95$	No	No
Essentials 100K	100 000	34,95$	No	No
Pro 100K	100 000	89,95$	1 incluida	Hasta 15
Pro 300K	300 000	249$	1 incluida	Hasta 15
Pro 700K	700 000	499$	1 incluida	Hasta 15
Premier	Personalizado	A medida	1 incluida	Hasta 15

Evolución importante: En mayo de 2025, SendGrid anunció la supresión del plan Free con un período de transición de 60 días. Los usuarios deben migrar a un plan de pago para continuar enviando emails.

Costes adicionales

• IP dedicada adicional: 30$/mes
• Email Validation API: 2 500 validaciones/mes incluidas (Pro), 5 000 (Premier), luego tarifación por uso
• Inbound Parse: incluido en todos los planes de pago
• Excesos: facturados prorrata (~0,001$/email en Pro)

Límites técnicos y rate limits

Rate limits por endpoint

Endpoint	Límite
v3 Mail Send	10 000 peticiones/segundo
API general	600 peticiones/minuto
Email Validation	7 peticiones/segundo

Cuando se alcanza el límite, la API devuelve un código HTTP 429. Los headers X-RateLimit-Remaining y X-RateLimit-Reset indican la cuota restante y el timestamp de reinicialización.

Gestión recomendada: backoff exponencial y puesta en cola local.

Cuotas por mensaje

Parámetro	Límite
Tamaño máximo email	30 MB
Destinatarios por mensaje	1 000
Categories por mensaje	10
Custom args	< 10 000 bytes
Grupos de unsubscribe	200 por cuenta

Gestión de supresiones

SendGrid mantiene automáticamente varias listas de supresión:

• Global Suppressions: desuscripciones globales
• Group Unsubscribes: vía ASM (Advanced Suppression Manager)
• Bounces: hard y soft
• Spam Reports
• Invalid Emails

Las direcciones se suprimen indefinidamente por defecto, con opción de purga configurable de 1 a 3650 días para bounces.

Event Webhook y tracking en tiempo real

El webhook de eventos permite recibir en tiempo real las notificaciones de delivery, engagement y compliance.

Eventos disponibles

• Delivery: processed, dropped, delivered, deferred, bounce
• Engagement: open, click, spamreport, unsubscribe
• ASM: group_unsubscribe, group_resubscribe

Comportamiento y retry

Los eventos se envían por lotes en 30 segundos o cuando el lote alcanza 768 KB. En caso de fallo (respuesta no-2xx), SendGrid reintenta durante 24 horas con intervalos crecientes.

Seguridad

La seguridad del webhook puede asegurarse mediante:

• Firma ECDSA: headers X-Twilio-Email-Event-Webhook-Signature y X-Twilio-Email-Event-Webhook-Timestamp
• OAuth 2.0 Client Credentials

Requisito: el endpoint debe soportar TLS 1.2 mínimo.

Inbound Parse

El Inbound Parse permite recibir y parsear los emails entrantes. La configuración necesita un registro MX apuntando hacia mx.sendgrid.net en un subdominio dedicado.

SendGrid extrae automáticamente:

• Headers
• Cuerpo (text y HTML)
• Archivos adjuntos
• Puntuación de spam (opcional)

Casos de uso: sistemas de ticketing, workflows de comunicación bidireccional.

Funcionalidades avanzadas

Email Validation API

Disponible solo en planes Pro y Premier. Utiliza machine learning entrenado con más de 100 mil millones de emails.

Verificaciones:

• Sintaxis
• Registros DNS
• Detección direcciones desechables
• Detección direcciones de rol
• Veredicto: Valid / Risky / Invalid + puntuación de confianza

Sandbox Mode

Permite probar el formato de las peticiones sin enviar realmente email.

Activado vía mail_settings.sandbox_mode.enable: true, hace lo siguiente:

• Valida la estructura JSON
• Devuelve un código 200 (vs 202 para envíos reales)
• No consume créditos

Categories y unique_args

Permiten un tracking granular:

• Categories: agrupación estadística (newsletters, receipts, alerts)
• unique_args (custom_args en v3): identificadores específicos (número de pedido, ID cliente) devueltos en los eventos webhook

Plan de acción: integración en 5 pasos

1. Crear la cuenta y generar una API key

• Crear una cuenta SendGrid (plan Essentials mínimo desde supresión del Free)
• Generar una API key en Settings > API Keys
• Definir los permisos (Full Access o Mail Send únicamente)

2. Configurar Domain Authentication

• Ir a Settings > Sender Authentication > Domain Authentication
• Activar Automated Security (recomendado)
• Crear los 3 registros CNAME en tu registrador:
  1. Return-Path (em1234.captaindns.com)
  2. DKIM s1 (s1._domainkey.captaindns.com)
  3. DKIM s2 (s2._domainkey.captaindns.com)
• Verificar la propagación DNS (24-48h)

3. Elegir el método de integración

Opción A: Web API v3

• Instalar el SDK oficial (npm install @sendgrid/mail, pip install sendgrid, etc.)
• Implementar el endpoint POST /v3/mail/send
• Crear Dynamic Templates si es necesario

Opción B: SMTP Relay

• Configurar tu app/plugin:
  • Host: smtp.sendgrid.net
  • Port: 587 (STARTTLS)
  • User: apikey
  • Password: tu API key

4. Configurar los webhooks

• Ir a Settings > Mail Settings > Event Webhook
• Definir la URL de tu endpoint (HTTPS + TLS 1.2)
• Seleccionar los eventos (delivered, bounced, etc.)
• Activar la firma ECDSA para la seguridad

5. Probar y monitorizar

• Enviar un email de prueba
• Verificar en Activity Feed que el email está bien entregado
• Verificar los eventos webhook
• Controlar las estadísticas (open rate, bounce rate)

FAQ

¿Por qué SendGrid utiliza dos selectores DKIM (s1 y s2)?

Los dos selectores permiten la rotación automática de claves DKIM sin interrupción del servicio. Cuando SendGrid quiere renovar las claves por razones de seguridad, puede generar una nueva clave en s2 mientras s1 todavía está activo, luego cambiar progresivamente el tráfico. Esto evita cualquier interrupción de entregabilidad durante el cambio de clave.

¿Debo añadir SendGrid en mi registro SPF?

No, con Domain Authentication y Automated Security, es innecesario. El CNAME Return-Path (em1234.captaindns.com) delega automáticamente la gestión SPF a SendGrid. Tu registro SPF principal no necesita mencionar SendGrid. Excepción: si también envías directamente desde tus servidores, debes incluirlos en tu SPF.

¿Cómo funciona la programación de envío con cancelación?

Utiliza send_at (timestamp Unix en segundos, máx 72h por adelantado). Para poder cancelar, genera primero un batch_id vía POST /v3/mail/batch, inclúyelo en la petición de envío, luego envía una cancelación al menos 10 minutos antes de la hora prevista vía POST /v3/user/scheduled_sends.

¿Cuál es el límite real de destinatarios por llamada API?

1 000 destinatarios máximo vía el array personalizations (to + cc + bcc combinados). Cada destinatario puede recibir contenido personalizado diferente vía dynamic_template_data. Para enviar a 10 000 personas, se necesitan 10 llamadas API (limitadas a 10 000 req/s).

¿Puedo utilizar el plan Essentials para producción crítica?

Sí, pero sin IP dedicada. El plan Essentials utiliza IP compartidas, exponiéndote a riesgos de reputación colectiva. Para emails transaccionales críticos (confirmaciones pedido, resets contraseña), se recomienda el plan Pro con IP dedicada desde 50 000 emails/mes. Por debajo, Essentials es suficiente si tu volumen es regular.

¿Cómo gestionar los rate limits de 10 000 req/s?

Implementar backoff exponencial y cola local. Monitorizar los headers X-RateLimit-Remaining y X-RateLimit-Reset. Si alcanzas 429, esperar el reset o ralentizar el ritmo. Para volúmenes muy grandes, usar múltiples API keys y distribuir las llamadas (rate limit por API key).

¿El header X-SMTPAPI funciona también con Web API v3?

No, X-SMTPAPI es específico del SMTP Relay. Con Web API v3, utiliza los parámetros JSON nativos: categories, custom_args, mail_settings (tracking), send_at (scheduling). La Web API ofrece un control más fino y estructurado que JSON en un header SMTP.

Glosario

• Web API v3: API REST de SendGrid para el envío de emails transaccionales. Endpoint principal: POST /v3/mail/send. Rate limit: 10 000 peticiones/segundo. Método recomendado para cualquier nueva integración.

• SMTP Relay: Servidor SMTP de SendGrid (smtp.sendgrid.net) que permite enviar vía el protocolo SMTP estándar. Autenticación: user apikey + password = API key. Puertos disponibles: 587 (TLS), 465 (SSL), 2525 (fallback).

• Personalizations: Array JSON en Web API v3 que permite enviar hasta 1 000 destinatarios por petición, cada uno recibiendo contenido personalizado vía dynamic_template_data.

• Dynamic Templates: Sistema de templates de SendGrid utilizando sintaxis Handlebars. Soporta variables, condiciones, bucles, comparaciones, formato de fechas. Triple llave {{{html}}} para HTML sin escapar.

• Domain Authentication: Configuración DNS para autenticar tu dominio con SendGrid. Con Automated Security: 3 CNAME (Return-Path + DKIM s1 + DKIM s2). Genera claves DKIM 2048 bits con rotación automática.

• Return-Path (Envelope From): Dirección técnica utilizada para el enrutamiento SMTP y los bounces. SendGrid utiliza un subdominio de tu dominio (em1234.captaindns.com), permitiendo la alineación SPF relaxed para DMARC. Personalizable vía Custom Return Path.

• Automated Security: Opción recomendada para Domain Authentication. Genera CNAME en lugar de TXT, permite la rotación automática de claves DKIM, y utiliza claves 2048 bits por defecto.

• IP Warmup: Proceso automático de escalado de una IP dedicada nueva. Calendario de 41 días: de 20 emails/hora (D1) a más de 19 millones/hora (D41). Evita el spam masivo y construye la reputación progresivamente.

• Subusers: Subcuentas aisladas con estadísticas, listas de supresión y webhooks propios. Disponibles en planes Pro y Premier (hasta 15 subusers). Permiten separar reputación por cliente o por flujo.

• IP Pools: Grupos de IP dedicadas asignables a diferentes flujos (transaccional vs marketing, por cliente, por marca). Refuerzan la separación de reputación.

• Event Webhook: Endpoint HTTP llamado por SendGrid durante eventos (delivered, bounced, opened, clicked). Envío por lotes (30s o 768 KB). Retry durante 24h en caso de fallo. Seguridad: firma ECDSA u OAuth 2.0.

• X-SMTPAPI: Header JSON específico del SMTP Relay para acceder a funcionalidades avanzadas (categories, unique_args, filtros, scheduling). Tamaño máx: 10 000 bytes. No se usa con Web API v3.

• Link Branding: Configuración DNS para reemplazar los dominios SendGrid en los enlaces rastreados por tu propio dominio. Requiere 2 CNAME adicionales. Mejora confianza y reputación.

• Sandbox Mode: Modo prueba que valida la estructura JSON sin enviar realmente. Activado vía mail_settings.sandbox_mode.enable: true. Devuelve código 200 (vs 202 en producción). No consume créditos.

• Email Validation API: Servicio de validación de direcciones email mediante machine learning (solo Pro/Premier). Verifica sintaxis, DNS, detecta desechables y roles. Veredicto: Valid / Risky / Invalid + puntuación.

• Inbound Parse: Servicio para recibir y parsear emails entrantes. Configuración: registro MX hacia mx.sendgrid.net en subdominio. Extrae headers, cuerpo, adjuntos, puntuación spam. Casos de uso: ticketing, comunicación bidireccional.

Fuentes oficiales

• SendGrid Official Documentation
• Twilio SendGrid Pricing