API

Nosūtīt e-pastu

POST /emails: viens ziņojums, tagad vai vēlāk.

POSTapi.openemail.uk/emails

Izpilda īstu izsaukumu pret jūsu darbvietu, ar jūsu paša atslēgu.

Pieprasījums

from ir obligāts. Atšķirībā no sastādītāja rezerves sūtītāja nav, jo šī rezerve ir darbvietas noklusējuma adrese un tā mainās nemanāmi, adresēm nākot un ejot.

Lauks	Obligāts	Piezīmes
from	jā	Kaila adrese vai `Name <addr>`. Jābūt tādai, kā atslēga drīkst sūtīt.
to	jā	Līdz 50 saņēmējiem kopā laukos to, cc un bcc.
cc, bcc	nē	Bcc saņēmēji nekad netiek nosaukti baitos, ko saņem kāds cits.
subject	nē	Pēc noklusējuma tukšs.
html, text	viens no	Abi ir pieļaujami. HTML ir tas, ko redz saņēmēji.
template	viens no	`{ id, version?, props?, slots? }`. Uzglabāts ķermenis, pēc id vai pēc slug. Kopā ar html, text vai `draftId` tiek noraidīts. Skatiet Sūtīšanu ar veidni.
replyTo	nē	Viena adrese.
headers	nē	`X-`, `List-`, Reply-To, Precedence, Auto-Submitted, Importance, Priority, Feedback-Id.
attachments	nē	`{ filename, content, contentType }` kā base64, kopā 5 MB, vai `{ fileId }`, nosaucot failu, kas jau ir darbvietā. 20 faili.
attachmentDelivery	nē	`mime`, `link` vai `auto`. `auto` pārvērš failus saitēs, tiklīdz tie pārsniedz 2 MB uz domēna ar aktīvu failu domēnu. Pēc noklusējuma izmanto pastkastes iestatījumu.
threadId	nē	Atbildēt esošā pavedienā.
draftId	nē	Nosūtīt esošu melnrakstu.
scheduledAt	nē	ISO moments vai ilgums. Skatiet Ieplānošanu.
cancellableForSeconds	nē	Atsaukšanas logs no 0 līdz 900 sekundēm tūlītējam sūtījumam. Kopā ar `scheduledAt` tiek noraidīts, jo tas paliek atceļams līdz nosūtīšanai. Skatiet Ieplānošanu.
signature	nē	`false` atstāj šo ziņojumu bez paraksta. Pretējā gadījumā tas nes tās adreses parakstu, no kuras tiek sūtīts, — vai nu šīs adreses pašas, vai to, kas iestatīts sadaļā Visas adreses.
tags	nē	Līdz 10 jūsu pašu birkām. Tiek atspoguļotas atpakaļ, nekad netiek interpretētas.
tracking	nē	`{ opens?, clicks? }`. Jebkurš no tiem pārraksta iestatījumu šim ziņojumam; izlaidiet lauku, un šī puse atgriežas pie tās adreses iestatījuma, no kuras sūta, vai pie Visām adresēm, un tā ir ieslēgta, ja vien kāds no tiem to nav izslēdzis.
translate	nē	`{ to, from?, subject?, includeOriginal? }`. Nosūta to saņēmēja valodā. Tiek atrisināts, kad pieprasījums pieņemts; kopā ar `draftId` tiek noraidīts.

Nezināmi lauki tiek noraidīti, nevis ignorēti, tāpēc nepareizi uzrakstīts nosaukums ir 422 tagad, nevis pārsteigums vēlāk. Galvenes, kas sagrautu sūtītāja autorizāciju (From, Sender, Bcc, Message-ID, Return-Path un citas), tiek noraidītas ar reserved_header.

Atbilde

200, kad ziņojums jau aizgājis, 202, kad ar to vēl kaut kam jānotiek. Izsaucējam, kas zaro pēc statusa koda, abos gadījumos ir taisnība.

200 OK

{  "object": "email",  "id": "msg_c5f21cc6bfec4e848caf905b",  "status": "sent",  "mode": "live",  "from": "[email protected]",  "subject": "Your September invoice",  "messageId": "<2598…@acme.com>",  "transport": "ses",  "sentAt": "2026-08-29T08:19:08.000Z",  "source": "api",  "replayed": false}

id ir noturīgais turētājs, ko paturat, un tas pats, uz kura atgriežas piegādes notikums, jo atlēciena webhook to nosauc kā emailId. messageId ir RFC 5322 Message-ID, un tas ir null, līdz eksistē MIME. Nekorelējiet pēc tā: sūtīšanas pakalpojums šo galveni ceļā pārraksta, tāpēc šī vērtība neparādās nevienā atlēciena vai piegādes ziņojumā un sakritība pēc tās nekad nenostrādā.

Saņēmēja valodā

translate pirms nosūtīšanas uzraksta ziņojumu kāda cita valodā. Pamatteksts un — ja vien to neizslēdzat — arī temats tiek tulkots brīdī, kad pieprasījums ir PIEŅEMTS; tas ir tas pats princips, ko ievēro template, un tas ir nesošs to pašu iemeslu dēļ: ieplānots ziņojums aiznes apstiprinātos vārdus, nevis to, ko modelis saģenerē otrdienā, un tulkojums, kuru nevarēja izgatavot, atsaka sūtīšanu, pirms vispār rodas ieraksts. Nekas netiek piegādāts valodā, kuru tā sūtītājs nav izvēlējies.

translate

tostringobligāts: Valoda, kurā rakstīt: BCP-47 kods (`de`), nosaukums angliski ("German") vai pašas valodas nosaukums ("Deutsch"), no 2 līdz 60 rakstzīmēm. Visi trīs varianti jau pašā sākumā tiek normalizēti uz tabulas kodu, tāpēc tie ir viens un tas pats pieprasījums — un tas ir svarīgi, jo Idempotency-Key nospiedums tiek ņemts no parsētā pieprasījuma. Nokārtojas arī aizstājvārdi: `zh-TW` kļūst par `zh-Hant`. Tāds, kas neatbilst nekam, ir 422 uz `translate.to`.
fromstring: Valoda, kurā rakstījāt, jebkurā no tām pašām trim formām. Tā ir tikai optimizācija. Ja to nenorāda, pamatteksts tiek izlasīts un valoda noteikta, un tas maksā vienu īsu modeļa izsaukumu. To ir vērts norādīt lielas slodzes ceļā, kā arī tad, kad pamatteksts galvenokārt sastāv no vārdiem, skaitļiem un saitēm: noteikšana labāk atturas, nekā min, un nenoteikts avots jums neizmaksā neko citu kā vien valodu, kas nosaukta parakstā virs jūsu oriģināla. Tas nav augšējā līmeņa `from`, kas ir adrese.
subjectboolean: Tulkot arī temata rindu. Noklusējums ir true; false nosūta tematu tieši tā, kā jūs to uzrakstījāt.
includeOriginalboolean: Zem tulkojuma — aiz atdalītāja un ar parakstu saņēmēja valodā — ievietot to, ko patiesībā uzrakstījāt. Noklusējums ir true, un to ir vērts atstāt ieslēgtu. Tikai tas ļauj lasītājam pārbaudīt teikumu, kas izklausās dīvaini, nevis prasa uzticēties modelim, kura izvadi neredz neviens no jums abiem.

curl

curl -X POST "$OE/emails" -H "$AUTH" -H "Content-Type: application/json" \  -d '{    "from": "[email protected]",    "to": ["[email protected]"],    "subject": "Your September invoice",    "html": "<p>Invoice attached. Payment is due on the 14th.</p>",    "translate": { "to": "de" }  }'

200 OK

{  "object": "email",  "id": "msg_c5f21cc6bfec4e848caf905b",  "status": "sent",  "from": "[email protected]",  "subject": "Ihre Rechnung für September",  "translation": {    "language": "de",    "languageName": "German",    "detectedSourceLanguage": "en",    "subject": true,    "includeOriginal": true  }}

translation ir papildinošs un parādās tikai ziņojumam, kas tika tulkots: šajā atbildē un GET /emails/{id}, nekad saraksta rindā, jo saraksts neielasa saglabāto pieprasījumu un tā klusēšana tur neliecina ne par ko. Tas nes kodus, nevis veselas valodu rindas: tas ir ieraksts par paveikto, bet endonīms dzīvo GET /languages. Atbildes subject ir tulkotais, tāpēc konsole nekad neuzrāda ziņojumu zem virknes, ko saņēmējs nekad nav redzējis.

Darbojas kopā ar template, un tieši tas ir noderīgais gadījums: tulkots tiek ATVEIDOTAIS rezultāts, tāpēc viens saglabāts pamatteksts apkalpo visas valodas, kurās lasa jūsu klienti. Veidne, kas atveido veselu dokumentu, vispirms tiek izjaukta: līdz modelim nonāk tikai tas, kas ir <body> iekšpusē, bet doctype, <style> bloki un @font-face noteikumi tiek atlikti atpakaļ ap atbildi. Tāpēc arī 30 000 rakstzīmju ierobežojums mēra tekstu, nevis dokumentu: divu rindu ziņojums, ietīts zīmola stila lapā, ir divu rindu ziņojums.
Vienīgā veidnes daļa, kas paliek netulkota, ir tās <title>, ko neviens pasta klients nerāda. react-email <Preview> tiek atveidots pamattekstā un tiek tulkots kopā ar pārējo.
Kopā ar draftId tas tiek atteikts: 422 uz translate, ar tekstu "A draft is sent as it was written; translate a body or send a draft, not both". Melnrakstu ir uzrakstījis cilvēks, un tas tiek nosūtīts tāds, kādu viņš to atstāja.
Apzināti nav daļa no idempotences nospieduma. Tiek jaukts pieprasījums, ko nosūtījāt, ieskaitot translate; tas, ko izgatavoja modelis, netiek. Tāpēc, atkārtojot neatbildētu sūtījumu ar to pašu Idempotency-Key, tiek atskaņots oriģināls. Atgriežas jau esošais ziņojums, bez otra sūtījuma un bez otra tulkojuma. Formulējuma jaukšana nozīmētu, ka godīgs atkārtots mēģinājums katru reizi dotu citu nospiedumu — un tieši tā viens un tas pats ziņojums aiziet divreiz.
Tulkots ziņojums, kas stāv rindā vai ir ieplānots, ir iesaldēts pret formulējuma izmaiņām. Pārvietojiet to vai atceliet; lai mainītu tā tekstu, tas ir jāatceļ un jānosūta no jauna — tāda cilvēka priekšā, kurš var izlasīt jaunos vārdus.
Mērķis, kas raksta no labās uz kreiso, arī tiek izgatavots no labās uz kreiso: tulkojums ietīts dir="rtl", bet jūsu oriģināls zem tā orientēts pats pēc sevis. Šis atribūts izdzīvo izejošo attīrītāju, kas dir atļauj tieši šī iemesla dēļ, tāpēc ziņojums uz vada nes to pašu virzienu, ko rādīja priekšskatījums.

Kods	Statuss	Kad
`invalid_parameter`	422	`translate.to` vai `translate.from` nosauc valodu, kuru nevaram atpazīt. Ziņojums norāda, kuras trīs formas tiek pieņemtas, un norāda uz `GET /languages`.
`unknown_language`	422	Tā pati kļūme, noķerta soli vēlāk — nevis shēmā, bet pakalpojumā. Rezerves tīkls, uz `translate.to`.
`translation_too_long`	422	Vairāk nekā 30 000 rakstzīmju vienā vai otrā modeļa izsaukuma galā. Atteikums, nevis apciršana: pustulkotam ziņojumam nav šuves, kas parādītu, kur tas apstājās, un lasītājs rīkojas pēc tās puses, kas viņam iedota.
`translation_not_configured`	409	Darbvietai nav AI atslēgas, un platformas AI ir izslēgts. 409, nevis 503, jo atkārtots mēģinājums neizdosies tieši tāpat. Nekas netika nosūtīts. Sūtiet bez `translate`, ja domājāt to sūtīt tā, kā uzrakstīts.
`translation_failed`	503	Pakalpojuma sniedzējs neatbildēja vai atbildēja ar kaut ko nelietojamu. Nekas netika nosūtīts; ziņojums nekad netiek izlikts netulkots kā atkāpšanās variants. Šī kļūda ir mūsu, un to ir vērts mēģināt vēlreiz.
`unknown_parameter`	422	Neatpazīta atslēga `translate` iekšpusē, kas ir strikts objekts tāpat kā pārējais pieprasījums.

Sūtījumam no koda nav neviena, kas vispirms izlasītu tulkojumu. POST /emails/translate ir tas pats brauciens, apturēts vienu soli agrāk, lai parādītu cilvēkam, ko viņš gatavojas nosūtīt. Pēc tam nosūtiet apstiprināto kā parastu html/subject bez jebkāda translate pieprasījumā.