Conecta un agente de IA con MCP

Qué es

El servidor MCP alojado de Postline está disponible en https://api.srs-postline.com/mcp y ofrece herramientas tipadas para correo, dominios, supresiones y webhooks.

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.
• Empieza con una clave srs_test_ contra un proyecto sandbox. El sandbox solo puede entregar a destinatarios que el usuario haya verificado, así que la entrega real a la bandeja de entrada requiere un proyecto live revisado — no prometas que el envío live funciona antes de que esa revisión se complete.
• Lee /llms.txt y openapi/postline.yaml antes de generar el código de las solicitudes; no adivines nombres de campos ni endpoints.

Conexión

Conecta el endpoint alojado con una clave Bearer de Postline; no necesitas descargar ni compilar nada.

claude mcp add --scope user --transport http postline \
  https://api.srs-postline.com/mcp \
  --header "Authorization: Bearer srs_live_xxx"

export POSTLINE_API_KEY='srs_live_xxx'
codex mcp add postline --url https://api.srs-postline.com/mcp \
  --bearer-token-env-var POSTLINE_API_KEY

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.
• 409 — conflicto de idempotencia; trata la solicitud original como ya enviada.
• 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.

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.