Referencia de SMTP

Para desarrolladores

Opciones de envío por header

Todas son opcionales. Un header que no esté en esta tabla se trata como header propio (ver Headers propios).

Header	Qué hace	Formato
x-fd-test-mode	Procesa el correo sin entregarlo. Útil para validar una integración.	true o false. Cualquier otro valor se rechaza con 554 5.6.0, así que un error de escritura no termina en un envío real.
x-fd-category	Clasifica el mensaje con una categoría. Se registra en su primer uso; no hace falta crearla antes.	texto, máx. 255. Se normaliza: Envíos Masivos queda como envios-masivos
x-fd-custom-group-code	Etiqueta de grupo libre (una campaña, un lote) para agrupar la actividad en los reportes.	texto, máx. 254
x-fd-custom-msg-id	Identificador propio del mensaje, para correlacionar los reportes con los registros internos de su sistema.	texto, máx. 254

Equivalencia con la API HTTP, para quien integra por los dos caminos:

Header SMTP	Campo JSON
x-fd-test-mode	test_mode
x-fd-category	category
x-fd-custom-group-code	custom_group_code
x-fd-custom-msg-id	custom_msg_id

Los valores enviados en estos headers quedan disponibles como filtros en GET /v1/mails y en los listados de actividad, igual que si el envío hubiera sido por HTTP.

El prefijo x-fd- está reservado a la plataforma. Un header x-fd-* que no sea uno de los cuatro de arriba se descarta y no se entrega al destinatario.

Headers propios

Cualquier otro header del mensaje se entrega al destinatario. Es el mecanismo para correlacionar (X-Order-Ref), para hilar conversaciones (In-Reply-To, References) o para cualquier metadato que el cliente de correo del destinatario deba ver.

Un valor largo se divide en varias líneas y, si no se puede dividir, se codifica según RFC 2047 (=?utf-8?q?...?=): un programa que lea el header sin procesar debe decodificarlo.

Estos headers no se pueden fijar, porque la plataforma los construye o los reescribe al entregar: Message-ID, Date, Return-Path, DKIM-Signature, List-Unsubscribe, List-Unsubscribe-Post, Sender, X-Mailer y Priority, más los que definen la estructura del mensaje (Content-Type, MIME-Version y similares).

Para hilar una conversación se usan In-Reply-To y References, no Message-ID: ese lo asigna la plataforma y se entrega con su propio valor.

Ejemplo de sesión

EHLO app.example.com
STARTTLS
AUTH LOGIN
MAIL FROM:<[email protected]>
RCPT TO:<[email protected]>
DATA
From: Notificaciones <[email protected]>
To: [email protected]
Subject: Su pedido fue confirmado
Reply-To: [email protected]
x-fd-category: transactional
x-fd-custom-msg-id: order-123
X-Order-Ref: order-123
Content-Type: text/html; charset=utf-8

<p>Su pedido fue confirmado.</p>
.
QUIT

En este mensaje, x-fd-category y x-fd-custom-msg-id alimentan los reportes y no viajan al destinatario; Reply-To y X-Order-Ref sí llegan al buzón de Alice.

Varios destinatarios

Una transacción SMTP (MAIL FROM, sus RCPT TO y DATA) es un mensaje, y puede ir a varios destinatarios:

• Cada destinatario se declara con su propio RCPT TO y recibe su propia copia. Cada copia tiene un identificador y una fila en los reportes, y se cobra por separado.
• Un buzón repetido en el sobre cuenta como un solo destinatario: recibe un correo y se cobra una vez.
• Varias transacciones en la misma conexión son mensajes distintos; el límite de destinatarios se aplica a cada uno.

Qué direcciones ve cada destinatario lo definen los headers del mensaje, no los RCPT TO del sobre:

• Las direcciones que escriba en To: y Cc: quedan a la vista de todos los destinatarios. La plataforma entrega esos headers tal como los recibió, sin reescribirlos por destinatario.
• Para una copia oculta (CCO), declare el destinatario en RCPT TO y no lo nombre en ningún header. Es lo que hace cualquier cliente de correo, y es lo que lo mantiene invisible para el resto. La otra forma de que no se vean entre sí es enviar un mensaje por destinatario.

Por API son los campos to, cc y bcc, con el mismo comportamiento (ver Enviar a varios destinatarios).

Límites

Qué	Límite	Qué pasa al excederlo
Subject	254 caracteres	El mensaje se rechaza con 554 5.6.0 antes de transferir el cuerpo. El límite se mide sobre el asunto decodificado, no sobre el header codificado: un asunto codificado en RFC 2047 ocupa bastante más, y esos caracteres extra no cuentan.
Adjuntos (peso total)	1 MB por defecto, configurable por instancia	El mensaje se acepta y se descarta después: termina en estado dropped y no se cobra. Desde la sesión SMTP no hay señal, así que para diagnosticarlo hay que consultar el estado del mensaje. Para ajustar el límite, solicítelo a soporte.
Destinatarios (RCPT TO)	50 por mensaje, contando los repetidos	El servidor responde 550 5.5.3 al comando DATA y el mensaje no se entrega a ninguno de sus destinatarios: no hay entrega parcial. Para llegar a más destinatarios, divida el envío en varios mensajes.
Destinatarios repetidos	Sin límite propio	No se rechaza: un buzón repetido en el sobre recibe un solo correo y se cobra una sola vez. La comparación no distingue mayúsculas.
Cuerpo del mensaje	Sin límite propio	El freno es el tamaño total del mensaje, en la fila siguiente.
Mensaje final (headers + cuerpo + adjuntos)	15 MB	El mensaje se rechaza con 552 5.3.4 (Message exceeds the maximum size accepted for delivery). Se mide sobre el mensaje ya codificado, que es alrededor de un 37% más grande que los archivos originales. Es un techo de la plataforma: no se ajusta por instancia.

Son los mismos límites que rigen para el envío por HTTP, donde el asunto y los destinatarios se rechazan con 422 y el mensaje con 413, en lugar de un código SMTP.

El código 552 5.3.4 también aparece con otro texto: Message exceeds instance bandwidth burst capacity. Ese rechazo no corresponde al límite de 15 MB. Depende del ancho de banda de la instancia y del número de destinatarios, así que puede afectar a un mensaje de menos de 15 MB. Para distinguir los dos casos, lea el texto del rechazo.

Consentimiento. Si el remitente está configurado para exigirlo, cada destinatario se evalúa por separado y el correo no sale hacia quien no lo tenga: el mensaje se acepta en la sesión SMTP y después queda en estado dropped, con el motivo registrado. Se comporta igual que el envío por HTTP. Detalle en la suite de consentimiento.

Diferencias con la API HTTP

	HTTP	SMTP
Respuesta con identificador del mensaje	sí (message_id)	no: se consulta por destinatario o por x-fd-custom-msg-id
Adjuntos	base64 o multipart	parte MIME estándar
Plantillas guardadas	sí (template_id)	no
Errores	HTTP con body problem+json	código SMTP + DSN

Para pruebas sin tocar destinatarios reales, ver sandbox.