API teatmik

Transaktsioonilise e-posti REST API

API võtab vastu autenditud päringuid, kontrollib projekti õiguste ulatust ja domeeni olekut, kontrollib suppression'it ning lisab vastuvõetud sõnumid järjekorda.

Uuendatud 24. juulil 2026Laadi alla OpenAPI 3.1

Autentimine

POST /v1/emails

Päring / Vastus

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

Sisendparameetrid

Parameeter	Tüüp	Kohustuslik	Kirjeldus	Näide
`Authorization`	`header · string`	Jah	Töölaual väljastatud piiratud API võti Bearer-tokenina.	`Bearer srs_live_…`
`Idempotency-Key`	`header · string`	Ei	Ühe loogilise saatmise püsiv identifikaator; tungivalt soovitatav.	`order_4821`
`from`	`string`	Jah	Saatja nimi ja aadress kinnitatud domeenil.	`Postline <info@example.com>`
`to`	`string[]`	Jah	Üks kuni 100 saaja e-posti aadressi.	`["user@example.net"]`
`subject`	`string`	Jah	Sõnumi teema.	`Teie tellimus on valmis`
`html`	`string`	Ei	HTML-sisu. Vähemalt üks väljadest html või text on kohustuslik.	`<p>…</p>`
`text`	`string`	Ei	Lihtteksti sisu. Vähemalt üks väljadest text või html on kohustuslik.	`Tellimus #4821…`

Vastusekoodid

Olek	HTTP	Kirjeldus
`202`	Accepted	Sõnum on järjekorras; see ei tähenda veel postkasti jõudmist.
`400`	Bad Request	Vigane JSON või toetamata väljad.
`401`	Unauthorized	API võti on vigane, aegunud või tühistatud.
`403`	Forbidden	Scope puudub või saatja domeen ei ole kinnitatud.
`422`	Unprocessable Entity	Saaja on suppression-loendis.
`429`	Too Many Requests	Projekti päringulimiit on ületatud.

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

{
  "error": "recipient suppressed"
}

Saada e-kiri

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

Põhiressursid

POST/v1/emailslisa sõnum järjekorda

GET/v1/emails/{id}vaata sõnumi olekut

POST/v1/domainslisa saatmisdomeen

POST/v1/domains/{id}/verifykäivita DNS-kontrollid

GET/POST/DELETE/v1/suppressionshalda mahasurutud saajaid (suppressions)

GET/POST/DELETE/v1/webhookshalda sündmuste lõpp-punkte (webhooks)

Vastuse mudel

202 tähendab, et sõnum on järjekorda lisatud, mitte postkasti toimetatud. 403 võib viidata puuduvale õiguste ulatusele või kinnitamata domeenile. 422 blokeerib mahasurutud (suppressed) saaja. 429 tähistab kiiruspiirangut (rate limiting).

Praegune juurdepääsumudel

Praegused võtmed kasutavad prefiksit srs_live_. Enne From-domeeni kinnitamist saab ühine sandbox-saatja saata ainult projekti liikmetele. Seejärel kehtivad paketipiirangud, suppression, saajapiirangud ja väärkasutuse kontroll. 202 tähendab järjekorda, mitte kohaletoimetamist.

Integratsiooniressursid

Kasuta inimeste ja AI-agentide samm-sammulist juhendit; väljade tõeallikas on OpenAPI.