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 la sección siguiente).

Header	Qué hace	Formato
x-fd-test-mode	Procesa el correo sin entregarlo. Útil para validar una integración.	true / false. Un valor que no sea booleano se rechaza con 554 5.6.0 en lugar de interpretarse como false, así que un typo no se traduce 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 arbitraria (campaña, batch) 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 plega y, si no tiene dónde plegarse, se codifica según RFC 2047 (=?utf-8?q?...?=): un consumidor que lea los bytes crudos debe decodificarlo.

Hay un conjunto que la plataforma administra y que no se puede fijar, porque 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:<noreply@example.com>
RCPT TO:<alice@example.org>
DATA
From: Notificaciones <noreply@example.com>
To: alice@example.org
Subject: Su pedido fue confirmado
Reply-To: soporte@example.com
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 a la casilla de Alice.

Límites

Qué	Límite	Qué pasa al excederlo
Subject	254 caracteres	La sesión SMTP se rechaza con 554 5.6.0 antes de transferir el cuerpo. El límite se mide sobre el asunto decodificado, no sobre el largo del header en el cable: 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. Solicitar un ajuste del límite a soporte.
Cuerpo del mensaje	Sin cota propia	El freno es el tamaño total del mensaje, en la fila siguiente.
Mensaje final (headers + cuerpo + adjuntos)	15 MB	La sesión SMTP se rechaza con 552 5.3.4 (Message exceeds the maximum size accepted for delivery) y el mensaje no se acepta. 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 se rechaza con 422 y el mensaje con 413, en lugar de un código SMTP.

Un segundo rechazo usa el mismo 552 5.3.4 con otro texto (Message exceeds instance bandwidth burst capacity) y no es el de esta tabla: ese depende del límite de ancho de banda de la instancia y del número de destinatarios, así que un mensaje que cabe en los 15 MB puede igual excederlo. Para distinguirlos, leer 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. Es exactamente el mismo comportamiento que por HTTP — la evaluación ocurre en una etapa por la que pasan los dos caminos de envío. 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 cuerpo problem+json	código SMTP + DSN

Para pruebas sin tocar destinatarios reales, ver sandbox.