API reference

Transactional email REST API

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

2026-10-13Download OpenAPI 3.1

Authentication

Send a scoped srs_live_ key from the dashboard as a Bearer token. Each key carries its own scopes (emails:send, webhooks:write …); revoked or expired keys are rejected with 401.

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	Recipient addresses; to + cc + bcc must not exceed 100 in total.	`["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…`
`cc / bcc`	`string[]`	No	Copy and blind-copy recipients (count toward the 100 limit).	`["team@example.com"]`
`reply_to`	`string[]`	No	Up to 10 reply-to addresses.	`["support@example.com"]`
`send_at`	`string · date-time`	No	Schedule delivery up to 30 days ahead (RFC 3339).	`2026-11-06T09:00:00Z`
`tags`	`object`	No	Up to 20 key/value tags for filtering.	`{"type":"receipt"}`
`headers`	`object`	No	Up to 8: In-Reply-To, References, List-Unsubscribe, List-Unsubscribe-Post.	`{"References":"<…>"}`
`template / variables`	`string / object`	No	Published template ID; fills subject and body from variables.	`"order-ready"`

Response codes

Status	HTTP	Description
`202`	Accepted	Message is queued; this does not mean inbox delivery.
`400`	Bad Request	Invalid JSON, unknown fields or failed validation (limits, attachments, headers).
`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 one message

POST/v1/emails/batchqueue up to 100 messages in one request

GET/v1/emailslist recent messages

GET/v1/emails/{id}message status

DELETE/v1/emails/{id}/schedulecancel a scheduled send

GET/POST/v1/domainslist or add sending domains

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

POST/v1/suppressionssuppress a recipient

GET/DELETE/v1/suppressions/{email}inspect or remove a suppression

GET/POST/v1/webhookslist or create webhook endpoints

DELETE/v1/webhooks/{id}delete an endpoint

GET/v1/webhooks/{id}/deliveriesdelivery attempts log

POST/v1/webhooks/{id}/deliveries/{deliveryId}/replayreplay a delivery

GET/POST/v1/templateslist or create templates

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 service limits

The REST API rejects attachments. It accepts only In-Reply-To, References, List-Unsubscribe and List-Unsubscribe-Post custom headers (up to 8). Hosted mail is separate: the web client supports up to 20 attachments, 25 MiB total; the released desktop client has a 10 MiB sending limit. HTTP 202 and email.accepted mean acceptance into the processing pipeline; SMTP acceptance does not guarantee delivery or inbox placement.

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.