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.

2026-10-13Laadi alla OpenAPI 3.1

Autentimine

Saada töölaual väljastatud piiratud srs_live_ võti Bearer-tokenina. Igal võtmel on oma scope’id (emails:send, webhooks:write …); tühistatud või aegunud võtmed lükatakse tagasi koodiga 401.

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	Saajate aadressid; to + cc + bcc kokku kuni 100.	`["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…`
`cc / bcc`	`string[]`	Ei	Koopia ja pimekoopia (arvestatakse 100 piiri sisse).	`["team@example.com"]`
`reply_to`	`string[]`	Ei	Kuni 10 vastamisaadressi.	`["support@example.com"]`
`send_at`	`string · date-time`	Ei	Ajastatud saatmine kuni 30 päeva ette (RFC 3339).	`2026-11-06T09:00:00Z`
`tags`	`object`	Ei	Kuni 20 võti/väärtus silti.	`{"type":"receipt"}`
`headers`	`object`	Ei	Kuni 8: In-Reply-To, References, List-Unsubscribe, List-Unsubscribe-Post.	`{"References":"<…>"}`
`template / variables`	`string / object`	Ei	Avaldatud malli ID; teema ja sisu muutujatest.	`"order-ready"`

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 üks sõnum järjekorda

POST/v1/emails/batchkuni 100 sõnumit ühe päringuga

GET/v1/emailsviimaste sõnumite loend

GET/v1/emails/{id}sõnumi olek

DELETE/v1/emails/{id}/scheduletühista ajastatud saatmine

GET/POST/v1/domainssaatmisdomeenide loend või lisamine

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

POST/v1/suppressionslisa saaja suppression-loendisse

GET/DELETE/v1/suppressions/{email}vaata või eemalda suppression

GET/POST/v1/webhookswebhook-lõpp-punktide loend või loomine

DELETE/v1/webhooks/{id}kustuta lõpp-punkt

GET/v1/webhooks/{id}/deliverieskohaletoimetamiskatsete logi

POST/v1/webhooks/{id}/deliveries/{deliveryId}/replaykorda kohaletoimetamist

GET/POST/v1/templatesmallide loend või loomine

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

Teenuse praegused piirangud

REST API ei toeta manuseid. Lubatud kohandatud päised on ainult In-Reply-To, References, List-Unsubscribe ja List-Unsubscribe-Post (kuni 8). Majutatud post on eraldi: veebiklient lubab 20 manust, kokku 25 MiB; avaldatud töölauakliendi saatmispiir on 10 MiB. HTTP 202 ja email.accepted tähendavad töötlemiseks vastuvõtmist; SMTP vastuvõtt ei taga kohaletoimetamist ega postkasti jõudmist.

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.