Integración con IA

Conecta el envío de correo para agentes de IA

Una ruta legible por máquinas para agentes de codificación y asistentes que necesitan añadir correo transaccional al proyecto de otra persona: qué llamar, en qué orden y qué comprobaciones ejecutar antes de cada envío.

Actualizado el 24 de julio de 2026Descargar OpenAPI 3.1

Antes de escribir cualquier código

Pide al usuario una clave de API del proyecto, o pídele que cree una clave de sandbox en https://app.srs-postline.com/es/login — nunca inventes, adivines ni reutilices una clave de otro proyecto.
Coloca la clave en una variable de entorno del lado del servidor. No la incluyas en código frontend, en el paquete de una app móvil, en un repositorio público ni en un archivo .env con commit realizado.
Lee /llms.txt y openapi/postline.yaml antes de generar el código de las solicitudes; no adivines nombres de campos ni endpoints.

Envío mínimo

POST /v1/emails
Authorization: Bearer srs_live_...
Idempotency-Key: <id-estable-por-envio-logico>
Content-Type: application/json

{
  "from": "Sender Name <info@example.com>",
  "to": ["user@example.net"],
  "subject": "Asunto",
  "html": "<p>Cuerpo</p>",
  "text": "Cuerpo"
}

Comprobaciones a ejecutar antes de cada envío

Envía siempre un Idempotency-Key derivado de la acción que dispara el envío (ID de pedido, ID de evento) para que los reintentos no puedan duplicar el envío.
Nunca pongas códigos OTP, tokens de restablecimiento de contraseña u otros secretos en un campo que se registre en logs o se reenvíe fuera del cuerpo del mensaje.
Solicita el scope de clave de API más restringido que la tarea necesite (emails:send es suficiente para enviar; no pidas domains:write ni api_keys:write a menos que la tarea lo requiera).
Limita los destinatarios por llamada a 100. La API actual no acepta adjuntos ni encabezados personalizados; rechaza el archivo o comparte un enlace sin afirmar que fue adjuntado.
No reintentes silenciosamente ante respuestas 4xx. Solo es seguro reintentar 429 y 503, y únicamente con backoff.

Gestiona todos los códigos de respuesta

202 — en cola, no entregado. Guarda el id devuelto si necesitas consultar el estado más tarde.
400 — payload inválido; corrige la solicitud, no reintentes sin cambios.
401 — clave inválida o caducada; detente y comunícaselo al usuario, no inventes una clave nueva.
403 — falta scope o el dominio de envío aún no está verificado; indica al usuario que verifique el dominio antes de continuar.
422 — el destinatario está suprimido (bounce/complaint previo); no reintentes con ese destinatario.
429 — limitado por tasa; espera y reintenta más tarde, no hagas bucles ajustados.
503 — cola no disponible; reintenta con backoff, no recurras a un transporte no oficial.

Si la tarea incluye recibir eventos

Registra un endpoint de webhook solo sobre HTTPS. Vuelve a calcular la firma tú mismo antes de confiar en cualquier payload; no omitas la verificación porque una solicitud «parezca interna».

signature = HMAC-SHA256(webhook_secret, timestamp + "\0" + event_id + "\0" + raw_body)

compara con el encabezado Postline-Signature (constant-time compare)
rechaza si Postline-Timestamp está fuera de tu ventana permitida
guarda event_id y procesa cada evento exactamente una vez

Referencias legibles por máquinas

/llms.txt — índice condensado de estas reglas para el contexto de agentes.
/openapi/postline.yaml — esquema OpenAPI 3.1 completo de cada endpoint.
/es/api/ — referencia de la API para humanos.
/es/webhooks/ — detalles de firma y reintentos de webhooks.

Modelo de acceso actual

Las claves actuales usan srs_live_. Antes de verificar el dominio From, el remitente sandbox compartido solo puede escribir a miembros del proyecto. Después, rigen cuotas, suppression, límites de destinatarios y controles de abuso. 202 significa en cola, no entregado.

Recursos de integración

Usa la guía práctica para personas y agentes de IA; OpenAPI es la fuente de verdad de los campos.