SMTP y API HTTP

Puede enviar a través de un flujo de dos maneras: por SMTP desde cualquier aplicación o biblioteca de correo, o con la API HTTP. Ambas usan las mismas claves de API, cuotas, lista de supresión y eventos. Antes de empezar, verifique un dominio de envío y cree una clave de API.

#Claves de API

1. Abra el flujo y vaya a la pestaña Clave de API.
2. Haga clic en Crear clave, introduzca un Nombre como production y confirme.
3. Copie la clave que se muestra y haga clic en Ya lo guardé. La clave solo se muestra esta vez. Después, la lista solo muestra su Prefijo, como ytm_aB3dE6gH….

Cada clave empieza por ytm_. Un flujo puede tener hasta 20 claves activas. La lista muestra cuándo se usó cada clave por última vez. Para retirar una clave, haga clic en Revocar: los programas que la usan dejan de funcionar de inmediato. Una clave solo funciona para el flujo al que pertenece.

#SMTP

La pestaña Resumen del flujo muestra la configuración SMTP:

Use el host que se muestra en la consola. Algunos flujos envían a través de otro grupo de servidores con su propio nombre de host.

Cómo funciona el envío por SMTP:

• El encabezado From debe usar una dirección de un dominio verificado para el flujo.
• Cada destinatario (To, Cc y Bcc) recibe su propia copia con su propio ID de mensaje, y cuenta como un correo.
• Para establecer una categoría, añada un encabezado como X-Yeap-Category: password-reset. Se elimina antes de la entrega. Los caracteres permitidos son letras, dígitos, ., _ y -, con un máximo de 64 caracteres.
• Un mensaje puede ocupar hasta 25 MB, con un máximo de 1,000 destinatarios por transacción SMTP.
• Cada mensaje recibe un encabezado X-TM-ID (el ID de mensaje que aparece en el registro de envíos y en los eventos) y un encabezado Feedback-ID para los bucles de retroalimentación de los proveedores de correo.
• En los flujos de marketing, cualquier encabezado List-Unsubscribe que usted establezca se sustituye por los encabezados de baja con un clic de Yeap Cloud. SMTP no modifica el cuerpo del mensaje, así que añada usted mismo su dirección postal y un enlace de baja al contenido. Consulte Supresiones y bajas.
• El seguimiento de aperturas y clics solo está disponible a través de la API HTTP.

Ejemplo con la biblioteca estándar de Python:

import smtplib
from email.message import EmailMessage

msg = EmailMessage()
msg["From"] = "Example <noreply@example.com>"
msg["To"] = "user@example.org"
msg["Subject"] = "Reset your password"
msg["X-Yeap-Category"] = "password-reset"
msg.set_content("Click the link to reset your password: https://example.com/reset/abc")

with smtplib.SMTP("smtp.tm.yeapcloud.net", 587) as s:
    s.starttls()
    s.login("apikey", "ytm_your_api_key")
    s.send_message(msg)

#Códigos de respuesta SMTP

Cuando el servidor rechaza un mensaje, el código de respuesta indica el motivo. Los códigos 4xx son temporales: vuelva a intentarlo más tarde. Los códigos 5xx son permanentes: corrija la causa antes de volver a enviar.

#API HTTP

Los errores devuelven un código de estado HTTP y un cuerpo como este:

{"error": {"code": "invalid_request", "message": "subject is required (single line)"}}

#Enviar un mensaje: POST /v1/send

Una sola llamada puede tener hasta 50 destinatarios en total entre to, cc y bcc. Cada destinatario recibe una copia independiente con su propio ID de mensaje. Para enviar contenido diferente a muchas personas, use el endpoint de lotes.

Ejemplo:

curl -X POST https://api.tm.yeapcloud.net/v1/send \
  -H "Authorization: Bearer ytm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Example <noreply@example.com>",
    "to": ["alice@example.org"],
    "subject": "Your order {{order_id}} has shipped",
    "html": "<p>Hi {{name}}, your order is on its way.</p>",
    "text": "Hi {{name}}, your order is on its way.",
    "category": "shipping",
    "tags": ["order"],
    "variables": {"name": "Alice", "order_id": "A-1024"}
  }'

Respuesta:

{
  "message_ids": ["01JAQ3Z9V8K4M2N6P7R5S1T0XW"],
  "rejected": []
}

message_ids enumera las copias aceptadas. rejected enumera los destinatarios a los que no se envió, cada uno con un rcpt y un reason. Una llamada puede tener éxito aunque se rechacen algunos destinatarios o incluso todos, así que compruebe siempre rejected:

Ejemplo en Python con requests:

import requests

resp = requests.post(
    "https://api.tm.yeapcloud.net/v1/send",
    headers={"Authorization": "Bearer ytm_your_api_key"},
    json={
        "from": "Example <noreply@example.com>",
        "to": "alice@example.org",
        "subject": "Welcome",
        "html": "<p>Welcome aboard!</p>",
        "text": "Welcome aboard!",
        "category": "welcome",
    },
    timeout=30,
)
resp.raise_for_status()
result = resp.json()
print(result["message_ids"], result["rejected"])

#Envío masivo: POST /v1/batch

Envíe hasta 500 mensajes en una sola solicitud. Cada elemento tiene los mismos campos que /v1/send.

{
  "messages": [
    {"from": "noreply@example.com", "to": "a@example.org", "subject": "Hi A", "text": "Hello A"},
    {"from": "noreply@example.com", "to": "b@example.org", "subject": "Hi B", "text": "Hello B"}
  ]
}

La respuesta contiene un resultado por mensaje, en el mismo orden:

{
  "results": [
    {"index": 0, "message_ids": ["01JAQ..."], "rejected": []},
    {"index": 1, "error": {"code": "invalid_request", "message": "subject is required (single line)"}, "rejected": []}
  ]
}

#Consultar mensajes: GET /v1/messages

La respuesta es {"data": [...], "next_before": "..."}. next_before es null en la última página. Los mensajes se conservan durante 30 días.

GET /v1/messages/{id} devuelve un mensaje y sus eventos:

{
  "id": "01JAQ3Z9V8K4M2N6P7R5S1T0XW",
  "stream_id": 12,
  "source": "api",
  "to": "alice@example.org",
  "from": "Example <noreply@example.com>",
  "subject": "Welcome",
  "category": "welcome",
  "tags": [],
  "status": "delivered",
  "smtp_code": 250,
  "smtp_response": "250 2.0.0 OK",
  "opened_at": null,
  "clicked_at": null,
  "unsubscribed_at": null,
  "created_at": "2026-10-20 10:15:02",
  "updated_at": "2026-10-20 10:15:04",
  "events": [
    {"type": "delivered", "at": "2026-10-20 10:15:04", "rcpt": "alice@example.org", "smtp_code": 250, "mx": "mx.example.org"}
  ]
}

#Supresiones: /v1/suppressions

Estos endpoints gestionan la lista de supresión del flujo de la clave de API.

Las direcciones añadidas a través de la API tienen el motivo manual. Las supresiones de toda la cuenta y las globales no se pueden modificar con la API. Consulte Supresiones y bajas.

#Relacionado

• Eventos y webhooks
• Límites, sandbox y cumplimiento
• Dominios de envío y DNS