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.

Actualizado el 24 de julio de 2026Descargar OpenAPI 3.1

Autenticación

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í	De una a 100 direcciones de correo de destinatarios.	`["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…`

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

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

POST/v1/domainsañade un dominio de envío

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

GET/POST/DELETE/v1/suppressionsgestiona destinatarios suprimidos

GET/POST/DELETE/v1/webhooksgestiona endpoints de eventos

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).

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.