Documentation

Start safely with Postline

Domain verification, API access, sandbox sending, suppression, and delivery events.

Updated 24 July 2026Open API reference

Production checklist

Verify ownership of the From domain.
Publish the supplied DKIM record and authorize the return-path infrastructure through SPF.
Production API keys are available immediately after signup.
Before domain verification, use sandbox@srs-postline.com only for a project-member recipient.
Configure DMARC alignment and review the result before sending to external recipients.
Process bounce and complaint webhooks idempotently and honor suppression decisions.

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

Authentication terminology

Postline DKIM-signs messages. SPF is an authorization policy published in DNS. DMARC evaluates alignment between the visible From domain and an authenticated SPF or DKIM identity; SPF and DMARC are not applied as message signatures.

TLS protects data in transit between supported hops. Ordinary email is not end-to-end encrypted, and the recipient provider can process message content.

Delivery outcomes

A recipient server accepting a message does not prove inbox placement. Treat accepted, deferred, hard bounce, soft bounce, complaint, suppressed, spam placement, and inbox placement as different outcomes.

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.