Enviar correo por SMTP

Para desarrolladores

Fidelizador acepta correo por SMTP autenticado (SMTP submission), como alternativa a la API HTTP. Úselo cuando su aplicación o sistema ya envía por SMTP: basta con una credencial SMTP y configurar su cliente con el servidor de Fidelizador.

API y SMTP usan el mismo proceso de entrega y generan los mismos reportes. En API las opciones se envían como campos del cuerpo JSON; en SMTP, como headers del mensaje.

Conexión

Parámetro	Valor
Host	cl2relay.fidelizador.com
Puerto	587 (STARTTLS) o 465 (TLS implícito)
Autenticación	obligatoria: usuario y contraseña de una credencial SMTP
Cifrado	obligatorio; no se acepta AUTH antes de TLS

Las credenciales SMTP se crean por dominio en el panel (ver Credenciales SMTP). El remitente del mensaje (From) debe pertenecer a un dominio verificado de la instancia.

Comprobar la credencial

Antes de configurar su aplicación, pruebe la credencial por separado con swaks:

swaks --to [email protected] \
      --from [email protected] \
      --server cl2relay.fidelizador.com:587 \
      --tls --auth -au "<usuario-de-la-credencial>" -ap "<contraseña>" \
      --header "Subject: Prueba de credencial"

--tls fuerza STARTTLS y --auth autentica. Un 250 final significa que Fidelizador aceptó el correo. Desde ahí, el estado de la entrega se consulta en los reportes, no en la sesión SMTP. Para probar sin llegar a un destinatario real, envíe a un destinatario *.sandbox (ver sandbox).

Los rechazos que puede ver en esta etapa:

Respuesta	Qué significa
550 5.7.1 Access denied	Credencial inexistente, revocada, con la contraseña equivocada, o su IP fuera de la lista permitida. El servidor no distingue el motivo: revise las cuatro cosas.
554 5.7.1 Sender ... not found	La dirección del remitente no corresponde a un remitente registrado sobre un dominio verificado.
554 5.7.1 Sender mismatch	El From del mensaje no coincide con el remitente del sobre (MAIL FROM).
554 5.6.0	Un valor inválido en un header x-fd-*, o el asunto supera los 254 caracteres.
550 5.5.3 Too many recipients	El mensaje trae más de 50 RCPT TO. Se rechaza al enviar DATA y no se entrega a ninguno de sus destinatarios. Divida el envío en mensajes de hasta 50. Con más de 100 RCPT TO, cada uno por encima del 100 recibe además 452 4.5.3. Reintentarlos no sirve: el mensaje se rechaza igual.

Enviar HTML desde Python

Los enlaces especiales (href="fide:unsubscribe" y otros) funcionan igual que por la API, en la parte HTML y en la de texto plano.

Con la librería estándar, EmailMessage arma el mensaje y smtplib lo entrega:

import smtplib
from email.message import EmailMessage

HOST = "cl2relay.fidelizador.com"
USER = "<usuario-de-la-credencial>"
PASSWORD = "<contraseña>"

message = EmailMessage()
message["From"] = "Notificaciones <[email protected]>"
message["To"] = "[email protected]"
message["Subject"] = "Su pedido fue confirmado"
message["Reply-To"] = "[email protected]"

# Opciones de la plataforma (ver "Opciones de envío por header" en la Referencia de SMTP).
message["x-fd-category"] = "transactional"
message["x-fd-custom-msg-id"] = "order-123"

# El texto plano primero y el HTML como alternativa: el cliente de correo
# elige, y un lector que no renderiza HTML igual recibe algo legible.
message.set_content("Su pedido fue confirmado.")
message.add_alternative("<p>Su pedido fue confirmado.</p>", subtype="html")

with smtplib.SMTP(HOST, 587) as smtp:
    smtp.starttls()
    smtp.login(USER, PASSWORD)
    smtp.send_message(message)

En el puerto 465 el cifrado es implícito, así que la conexión se abre ya cifrada y no hay starttls() que llamar:

with smtplib.SMTP_SSL(HOST, 465) as smtp:
    smtp.login(USER, PASSWORD)
    smtp.send_message(message)

send_message no devuelve un identificador del mensaje, porque el protocolo no lo entrega. Para correlacionar con sus propios registros, use x-fd-custom-msg-id como en el ejemplo y consulte después por ese valor (ver Diferencias con la API HTTP).

ℹ️ Nota. Los adjuntos se envían por SMTP como una parte MIME estándar, sujeta a los Límites. Si su integración necesita adjuntos, la API HTTP los recibe en un campo, sin armar el MIME.