API reference

Transactional email REST API

The API accepts authenticated requests, verifies project scope and domain state, checks suppression, then queues accepted messages.

Updated 24 July 2026Download OpenAPI 3.1

Authentication

Send a scoped srs_live_ key as a Bearer token. Revoked or expired keys are rejected.

POST /v1/emails

Request / Response

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"
}

Input parameters

Parameter	Type	Required	Description	Example
`Authorization`	`header · string`	Yes	Dashboard-issued scoped API key as a Bearer token.	`Bearer srs_live_…`
`Idempotency-Key`	`header · string`	No	Stable identifier for one logical send; strongly recommended.	`order_4821`
`from`	`string`	Yes	Sender name and address on a verified domain.	`Postline <info@example.com>`
`to`	`string[]`	Yes	One to 100 recipient email addresses.	`["user@example.net"]`
`subject`	`string`	Yes	Message subject.	`Your order is ready`
`html`	`string`	No	HTML body. Either html or text is required.	`<p>…</p>`
`text`	`string`	No	Plain-text body. Either text or html is required.	`Order #4821…`

Response codes

Status	HTTP	Description
`202`	Accepted	Message is queued; this does not mean inbox delivery.
`400`	Bad Request	Invalid JSON or unsupported fields.
`401`	Unauthorized	API key is invalid, expired, or revoked.
`403`	Forbidden	Missing scope or sender domain is not verified.
`422`	Unprocessable Entity	A recipient is on the suppression list.
`429`	Too Many Requests	Project rate limit was exceeded.

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

{
  "error": "recipient suppressed"
}

Send an email

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

Core resources

POST/v1/emailsqueue a message

GET/v1/emails/{id}inspect message state

POST/v1/domainsadd a sending domain

POST/v1/domains/{id}/verifyrun DNS checks

GET/POST/DELETE/v1/suppressionsmanage suppressed recipients

GET/POST/DELETE/v1/webhooksmanage event endpoints

Response model

202 means queued, not inboxed. 403 can indicate missing scope or an unverified domain. 422 blocks a suppressed recipient. 429 indicates rate limiting.

Current access model

Current dashboard keys use srs_live_. Before a customer From-domain is verified, use the shared sandbox sender only for project-member recipients. After DNS verification, external sending is governed by plan quotas, suppression, recipient throttles, and abuse controls. A 202 response means queued, not delivered.

Integration resources

Use the copy-paste guide for humans and AI agents, and treat OpenAPI as the field-level source of truth.