Enviar correo electrónico por SMTP

Si tu aplicación ya soporta SMTP, apúntala a nuestro relay cambiando el host, el puerto y las credenciales. Frameworks, sistemas de gestión de contenido, impresoras y cualquier otro software que pueda enviar correo a un relay SMTP pueden usar esta vía.

El correo enviado por SMTP se trata exactamente igual que el correo enviado a través de la API de email: la misma verificación de dominio, pools de IP, firma DKIM, gestión de supresiones, seguimiento, eventos y analíticas. SMTP es una segunda vía de entrada al mismo producto, así que todo lo que configures en una se aplica a la otra.

Elige el servicio de relay SMTP cuando quieras conservar el código de construcción de mensajes que ya tiene tu aplicación. Elige la API de email cuando necesites campos de solicitud estructurados o plantillas almacenadas. SMTP toma el contenido del mensaje MIME y las opciones de envío de la configuración de la clave API.

Qué necesitas primero

• Un dominio de envío verificado. La dirección que pongas en MAIL FROM (y en el encabezado From del mensaje) debe pertenecer a un dominio que hayas verificado en este espacio de trabajo. Consulta Dominios de envío.
• Una clave API con el scope emails. SMTP usa tus claves API normales y no requiere una credencial SMTP independiente. Crea una clave en Developers > Claves API con el envío de email habilitado. Una clave sin el scope emails no puede enviar, y tampoco una clave de solo verify.

Configuración de conexión

Apunta tu cliente al host SMTP de la región de tu clave. La región es el prefijo en la propia clave: una clave bk_eu1_... envía a través del host eu1, una clave bk_us1_... a través de us1. Autenticarse con una clave de la otra región falla con una respuesta 535 que indica el host correcto.

Usa el que soporte tu cliente:

• Puerto 465, TLS implícito (SMTPS). La conexión se cifra desde el primer byte, antes de enviar cualquier comando. En la mayoría de las bibliotecas es la opción "SSL/TLS" o "SMTPS".
• Puertos 587 y 2525, STARTTLS. La conexión se abre en texto plano y se actualiza a TLS con el comando STARTTLS antes de la autenticación. Es la opción "STARTTLS", a veces etiquetada simplemente como "TLS". Usa 2525 si tu red bloquea el 587.

Versiones de TLS: Los puertos 465, 587 y 2525 admiten TLS 1.2 y TLS 1.3. Configura tu cliente para usar TLS 1.2 o posterior. TLS 1.0 y TLS 1.1 no están soportados.

En ambos casos la sesión está cifrada antes de que se envíen tus credenciales, por lo que nunca viajan en texto plano: en 587 y 2525 AUTH se rechaza hasta que STARTTLS se haya ejecutado. El puerto 25 no se ofrece para envío.

Autenticación

Autentícate con AUTH PLAIN o AUTH LOGIN. El nombre de usuario es la cadena literal bird y la contraseña es tu clave API:

Username: bird
Password: bk_eu1_your_api_key

El nombre de usuario es un literal fijo y no tiene identidad propia. La clave API en el campo de contraseña es lo que autentica. En la mayoría de herramientas SMTP pegas tu clave API en el campo de contraseña y estableces el nombre de usuario como bird. Revocar la clave corta su envío por SMTP en segundos, incluso a mitad de conexión.

Qué viene del mensaje y qué viene de la configuración de la clave

Todo lo que tiene un lugar natural en un mensaje MIME viene del propio mensaje: las cabeceras From, To, Cc y Reply-To, el asunto, los cuerpos HTML y texto, y los archivos adjuntos e imágenes en línea. Los destinatarios se toman del sobre SMTP (RCPT TO). Una dirección en RCPT TO que no aparece en una cabecera visible To o Cc se trata como Bcc. Un mensaje puede tener como máximo 50 destinatarios entre to, cc y bcc, y el tamaño total del mensaje está limitado a 20 MB.

Las opciones de envío que no tienen un lugar estándar en un mensaje MIME vienen de la configuración SMTP de la clave. Incluyen el pool de IP, la categoría, las etiquetas y el seguimiento de aperturas y clics. Una clave sin configurar usa el pool predeterminado de tu organización, la categoría transactional y el seguimiento activado. Configura la clave en Email > SMTP, o llama a la SMTP config API. Asigna a cada aplicación su propia clave cuando necesite valores predeterminados distintos. Los cambios se aplican a los mensajes nuevos sin reconectar el cliente.

Una sesión completa

En el puerto 465 el cliente abre primero la conexión TLS y luego ejecuta todo el diálogo SMTP dentro de ella:

   ... TLS handshake ...
S: 220 eu1.smtp.bird.com ESMTP Service Ready
C: EHLO myapp
S: 250-Hello myapp
   250-PIPELINING
   250-8BITMIME
   250-ENHANCEDSTATUSCODES
   250-CHUNKING
   250-AUTH PLAIN LOGIN
   250-SIZE 20971520
   250 LIMITS RCPTMAX=50
C: AUTH PLAIN <base64 of bird + key>
S: 235 2.0.0 Authentication succeeded
C: MAIL FROM:<news@yourdomain.com>
C: RCPT TO:<delivered@messagebird.dev>
C: DATA
   ... your MIME message ...
C: .
S: 250 2.0.0 Ok: queued as em_01ky7ma8y2es1s2akzk53tmjn0

En el puerto 587 o 2525 el cliente se conecta en texto plano, emite STARTTLS para actualizar la conexión y luego ejecuta el mismo diálogo dentro de TLS. AUTH no se ofrece hasta que la actualización se completa:

S: 220 eu1.smtp.bird.com ESMTP Service Ready
C: EHLO myapp
S: 250-Hello myapp
   250-PIPELINING
   250-8BITMIME
   250-ENHANCEDSTATUSCODES
   250-CHUNKING
   250-STARTTLS
   250-SIZE 20971520
   250 LIMITS RCPTMAX=50
C: STARTTLS
S: 220 2.0.0 Ready to start TLS
   ... TLS handshake ...
C: EHLO myapp
S: 250-Hello myapp
   250-PIPELINING
   250-8BITMIME
   250-ENHANCEDSTATUSCODES
   250-CHUNKING
   250-AUTH PLAIN LOGIN
   250-SIZE 20971520
   250 LIMITS RCPTMAX=50
C: AUTH PLAIN <base64 of bird + key>
S: 235 2.0.0 Authentication succeeded
C: MAIL FROM:<news@yourdomain.com>
C: RCPT TO:<delivered@messagebird.dev>
C: DATA
   ... your MIME message ...
C: .
S: 250 2.0.0 Ok: queued as em_01ky7ma8y2es1s2akzk53tmjn0

El 250 final devuelve el ID del mensaje en cola, el mismo ID em_... que obtendrías de la API. Puedes buscar el mensaje por ese ID en el Email log o a través de GET /v1/email/messages/{message_id}.

Reintentar de forma segura

El pipeline acepta un mensaje y lo entrega de forma asíncrona, y los clientes SMTP reintentan de forma agresiva cuando se cae una conexión. Para que un reintento sea seguro, añade un encabezado X-Bird-Idempotency-Key al mensaje: una repetición dentro de la ventana de retención devuelve el ID del mensaje que ya estaba en cola en lugar de enviar una segunda copia. Usa un valor estable para el mensaje lógico, como un ID de pedido o un ID de notificación. Evita generar un valor aleatorio en cada intento.

Guarda el ID del mensaje en cola junto con el evento de la aplicación que originó el envío. Si la conexión se cae antes de recibir la respuesta final, reintenta ese mensaje lógico con la misma clave. Tras la ventana de retención, un reintento puede crear otro mensaje. Conserva tu propio registro de envío para recuperarte más allá de esa ventana.

Límites de conexión

Cada organización puede mantener hasta 10 conexiones SMTP autenticadas simultáneas de forma predeterminada. Una conexión cuenta desde la autenticación hasta que se cierra, en todos los servidores y claves API de la organización. Cuando se alcanza el límite, otra conexión recibe una respuesta transitoria 421 tras la autenticación. Reutiliza conexiones, reduce la concurrencia y reintenta. El límite cuenta las conexiones abiertas de forma independiente del volumen de mensajes. Email > SMTP muestra las conexiones activas respecto al límite.

Dimensiona tu pool de conexiones en función del límite de conexiones de la organización. Ajusta el ritmo de los envíos a las cuotas de envío. Los encabezados de limitación de solicitudes de HTTP describen solicitudes API; no son una cuota de velocidad de envío de SMTP.

Gestionar respuestas SMTP

SMTP reporta un dominio de envío no verificado, un dominio de destinatario reservado, un pool de IP inutilizable, un tipo de adjunto bloqueado o un mensaje malformado con una respuesta permanente 550. Un mensaje que supera el límite de 20 MB devuelve 552. Una cuota de envío superada o un número de destinatarios superior a 50 devuelve una respuesta transitoria 452. Los destinatarios suprimidos se gestionan de forma asíncrona: SMTP acepta el mensaje y luego cada destinatario suprimido aparece como rejected en el registro de correo y en los eventos.

Para decidir qué interfaz usar, compara el envío y la recuperación con SMTP y HTTP. Ambas vías ponen el trabajo en cola antes de la entrega al destinatario. Un evento email.delivered registra la aceptación por parte del servidor receptor. Ese evento no confirma la colocación en la bandeja de entrada.

Próximos pasos

• Dominios de envío: verifica el dominio desde el que enviarás.
• IPs dedicadas y pools: elige desde qué pool envía una clave.
• Supresiones: por qué un destinatario aceptado podría no recibir un mensaje.
• Registro de correo: busca un mensaje por el ID que devolvió SMTP.