AI integratsioon

Seadista e-posti saatmine AI-agentide jaoks

Masinloetav juhend koodiagentidele ja assistentidele, kes peavad lisama transaktsioonilise e-posti kellegi teise projekti — mida kutsuda, mis järjekorras ja milliseid kontrolle teha enne iga saatmist.

Laadi alla OpenAPI 3.1

Enne koodi kirjutamist

  • Küsi kasutajalt projekti API-võti või lase tal luua sandbox-võti aadressil https://app.srs-postline.com/et/login — ära kunagi leiuta, arva ega taaskasuta teise projekti võtit.
  • Pane võti serveripoolsesse keskkonnamuutujasse. Ära pane seda frontend-koodi, mobiilirakenduse pakki, avalikku repositooriumisse ega commititud .env-faili.
  • Loe /llms.txt ja openapi/postline.yaml enne päringukoodi genereerimist; ära arva väljade nimesid ega lõpp-punkte.

Minimaalne saatmine

POST /v1/emails
Authorization: Bearer srs_live_...
Idempotency-Key: <stabiilne-id-loogilise-saatmise-kohta>
Content-Type: application/json

{
  "from": "Sender Name <info@example.com>",
  "to": ["user@example.net"],
  "subject": "Teema",
  "html": "<p>Sisu</p>",
  "text": "Sisu"
}

Kontrollid enne iga saatmist

  • Saada alati Idempotency-Key, mis on tuletatud käivitavast toimingust (tellimuse ID, sündmuse ID), et kordussaatmised ei saadaks sõnumit topelt.
  • Ära kunagi pane OTP-koode, parooli lähtestamise tokeneid ega muid saladusi väljale, mida logitakse või edastatakse väljapoole sõnumi sisu.
  • Küsi kitsaimat API-võtme õiguste ulatust, mida ülesanne vajab (saatmiseks piisab emails:send-ist; ära küsi domains:write ega api_keys:write, kui ülesanne seda ei nõua).
  • Piira saajate arv 100-ni kõne kohta. Praegune API ei aktsepteeri manuseid ega kohandatud päiseid; lükka fail tagasi või jaga linki, väitmata, et fail lisati manusena.
  • Ära korda vaikimisi 4xx vastuste puhul. Ainult 429 ja 503 on turvaline korrata, ja seda ainult viivitusega (backoff).

Käsitle iga vastusekoodi

  • 202 — järjekorda lisatud, mitte kohale toimetatud. Salvesta tagastatud id, kui pead hiljem olekut kontrollima.
  • 400 — vigane päring (payload); paranda päring, ära korda muutmata kujul.
  • 401 — vigane või aegunud võti; peata ja anna sellest kasutajale teada, ära leiuta uut võtit.
  • 403 — puudub õiguste ulatus või saatev domeen ei ole veel kinnitatud; palu kasutajal domeen enne jätkamist kinnitada.
  • 422 — saaja on mahasurutud (varasem bounce/complaint); ära korda saatmist sellele saajale.
  • 429 — kiiruspiirang; oota ja proovi hiljem uuesti, ära tsükli kiirelt.
  • 503 — järjekord ei ole saadaval; proovi uuesti viivitusega, ära lülitu mitteametlikule edastusviisile.

Kui ülesanne hõlmab sündmuste vastuvõtmist

Registreeri webhook-lõpp-punkt ainult HTTPS-i kaudu. Arvuta signatuur ise uuesti enne payload'i usaldamist; ära jäta kontrolli vahele lihtsalt sellepärast, et päring 'näib olevat sisemine'.

signature = HMAC-SHA256(webhook_secret, timestamp + "\0" + event_id + "\0" + raw_body)

võrdle päisega Postline-Signature (constant-time võrdlus)
lükka tagasi, kui Postline-Timestamp on lubatud ajaakna välisel
salvesta event_id ja töötle iga sündmust täpselt üks kord

Masinloetavad viited

  • /llms.txt — nende reeglite kokkuvõtlik indeks agendi kontekstiakna jaoks.
  • /openapi/postline.yaml — kõigi lõpp-punktide täielik OpenAPI 3.1 skeem.
  • /et/api/ — inimloetav API teatmik.
  • /et/webhooks/ — webhooki signatuuri ja korduskatsete üksikasjad.

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.