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.

Región	Host
EU	eu1.smtp.bird.com
US	us1.smtp.bird.com

Puerto	Cifrado
465	TLS implícito (SMTPS)
587	STARTTLS
2525	STARTTLS

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.

En ambos casos la sesión se cifra antes de enviar tus credenciales, por lo que nunca viajan en texto plano: en los puertos 587 y 2525 AUTH se rechaza hasta que STARTTLS se haya completado. El puerto 25 no está disponible 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:

Ejemplo de código

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 las 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 SMTP en segundos, incluso en conexiones activas.

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: los encabezados 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 envelope SMTP (RCPT TO). Una dirección en RCPT TO que no esté en un encabezado 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 habilitado. Configura la clave en Email > SMTP, o llama a la API de config SMTP. Asigna a cada aplicación su propia clave cuando necesite valores predeterminados distintos. Los cambios se aplican a los mensajes nuevos sin necesidad de 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:

Ejemplo de código

   ... 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 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:

Ejemplo de código

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 Registro de email 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 agresivamente 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 ya 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 causó el envío. Si la conexión se cae antes de recibir la respuesta final, reintenta ese mensaje lógico con la misma clave. Después de la ventana de retención, un reintento puede crear otro mensaje. Mantén tu propio registro de envíos para recuperación más allá de esa ventana.

Límites de conexión

Cada organización puede mantener hasta 10 conexiones SMTP autenticadas simultáneas por defecto. Una conexión cuenta desde la autenticación hasta que se cierra, a través de todos los servidores y claves API de la organización. Alcanzado el límite, otra conexión recibe una respuesta transitoria 421 después de la autenticación. Reutiliza conexiones, reduce la concurrencia y reintenta. El límite cuenta conexiones abiertas de forma independiente al volumen de mensajes. Email > SMTP muestra las conexiones activas frente al límite.

Dimensiona tu pool de conexiones según el límite de conexiones de la organización. Regula los envíos según las cuotas de envío. Los encabezados de limitación de solicitudes de HTTP describen solicitudes API; no son una concesión de tasa de envío SMTP.

Manejar respuestas SMTP

SMTP reporta un dominio de envío no verificado, dominio de destinatario reservado, pool de IP no utilizable, tipo de adjunto bloqueado o mensaje malformado con una respuesta permanente 550. Un mensaje que supere el límite de 20 MB devuelve 552. Una cuota de envío excedida o un recuento 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 email y en los eventos.

Para decidir entre interfaces, compara el envío y la recuperación por 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 el servidor receptor. Ese evento no garantiza 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 email: busca un mensaje por el ID que devolvió SMTP.

Recursos relacionados

Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.

Explorar la funcionalidadSMTP relay