Referencia de la API

API REST de correo transaccional

La API acepta solicitudes autenticadas, verifica el scope del proyecto y el estado del dominio, comprueba el suppression y luego pone en cola los mensajes aceptados.

2026-10-13Descargar OpenAPI 3.1

Autenticación

Envía una clave srs_live_ con scope emitida en el panel como token Bearer. Cada clave tiene sus propios scopes (emails:send, webhooks:write …); las claves revocadas o caducadas se rechazan con 401.

POST /v1/emails

Solicitud / Respuesta

curl --request POST 'https://api.srs-postline.com/v1/emails' \
  --header 'Authorization: Bearer srs_live_...' \
  --header 'Idempotency-Key: order_4821' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "from": "Postline <info@example.com>",
    "to": ["user@example.net"],
    "subject": "Your order is ready",
    "html": "<p>Order #4821 is ready.</p>",
    "text": "Order #4821 is ready."
  }'

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "id": "msg_01JPOSTLINEEXAMPLE",
  "status": "queued",
  "created_at": "2026-08-22T12:00:00Z"
}

Parámetros de entrada

Parámetro	Tipo	Obligatorio	Descripción	Ejemplo
`Authorization`	`header · string`	Sí	Clave de API con alcance emitida por el panel como token Bearer.	`Bearer srs_live_…`
`Idempotency-Key`	`header · string`	No	Identificador estable para un envío lógico; muy recomendado.	`order_4821`
`from`	`string`	Sí	Nombre y dirección del remitente en un dominio verificado.	`Postline <info@example.com>`
`to`	`string[]`	Sí	Direcciones de destinatarios; to + cc + bcc no pueden superar 100 en total.	`["user@example.net"]`
`subject`	`string`	Sí	Asunto del mensaje.	`Tu pedido está listo`
`html`	`string`	No	Cuerpo HTML. Es obligatorio enviar html o text.	`<p>…</p>`
`text`	`string`	No	Cuerpo de texto plano. Es obligatorio enviar text o html.	`Pedido #4821…`
`cc / bcc`	`string[]`	No	Copia y copia oculta (cuentan para el límite de 100).	`["team@example.com"]`
`reply_to`	`string[]`	No	Hasta 10 direcciones de respuesta.	`["support@example.com"]`
`send_at`	`string · date-time`	No	Programa el envío hasta 30 días (RFC 3339).	`2026-11-06T09:00:00Z`
`tags`	`object`	No	Hasta 20 etiquetas clave/valor.	`{"type":"receipt"}`
`headers`	`object`	No	Hasta 8: In-Reply-To, References, List-Unsubscribe, List-Unsubscribe-Post.	`{"References":"<…>"}`
`template / variables`	`string / object`	No	ID de plantilla publicada; asunto y cuerpo desde variables.	`"order-ready"`

Códigos de respuesta

Estado	HTTP	Descripción
`202`	Accepted	El mensaje está en cola; aún no significa entrega en la bandeja de entrada.
`400`	Bad Request	JSON no válido o campos no compatibles.
`401`	Unauthorized	La clave API no es válida, ha caducado o fue revocada.
`403`	Forbidden	Falta el scope o el dominio del remitente no está verificado.
`422`	Unprocessable Entity	El destinatario está en la lista de supresión.
`429`	Too Many Requests	Se superó el límite de solicitudes del proyecto.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": "recipient suppressed"
}

Enviar un correo

POST /v1/emails
Authorization: Bearer srs_live_…
Idempotency-Key: reset-4821
Content-Type: application/json

Recursos principales

POST/v1/emailspone en cola un mensaje

POST/v1/emails/batchhasta 100 mensajes en una solicitud

GET/v1/emailslista mensajes recientes

GET/v1/emails/{id}estado del mensaje

DELETE/v1/emails/{id}/schedulecancela un envío programado

GET/POST/v1/domainslista o añade dominios de envío

POST/v1/domains/{id}/verifyejecuta comprobaciones DNS

POST/v1/suppressionssuprime un destinatario

GET/DELETE/v1/suppressions/{email}consulta o elimina una supresión

GET/POST/v1/webhookslista o crea endpoints de webhook

DELETE/v1/webhooks/{id}elimina un endpoint

GET/v1/webhooks/{id}/deliveriesregistro de intentos de entrega

POST/v1/webhooks/{id}/deliveries/{deliveryId}/replayreenvía una entrega

GET/POST/v1/templateslista o crea plantillas

Modelo de respuesta

202 significa en cola, no entregado en la bandeja de entrada. 403 puede indicar falta de scope o un dominio sin verificar. 422 bloquea a un destinatario suprimido. 429 indica limitación de tasa (rate limiting).

Límites actuales del servicio

La API REST rechaza adjuntos. Solo admite los encabezados personalizados In-Reply-To, References, List-Unsubscribe y List-Unsubscribe-Post (hasta 8). El correo alojado es independiente: la web admite hasta 20 adjuntos y 25 MiB en total; el cliente de escritorio publicado limita los envíos a 10 MiB. HTTP 202 y email.accepted significan aceptación para procesamiento; la aceptación SMTP no garantiza entrega ni llegada a la bandeja de entrada.

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.