API

Dërgoni një email

POST /emails: një mesazh, tani ose më vonë.

POSTapi.openemail.uk/emails

Ekzekuton thirrjen reale kundrejt hapësirës suaj të punës, me çelësin tuaj.

Kërkesa

from është i detyrueshëm. Ndryshe nga hartuesi, nuk ka dërgues rezervë, sepse rezerva është adresa e parazgjedhur e hapësirës së punës dhe ndryshon në mënyrë të padukshme ndërsa adresat vijnë e shkojnë.

Fusha	E detyrueshme	Shënime
from	po	Një adresë e thjeshtë ose `Name <addr>`. Duhet të jetë një nga ato me të cilat çelësi lejohet të dërgojë.
to	po	Deri në 50 marrës gjithsej mes to, cc dhe bcc.
cc, bcc	jo	Marrësit në bcc nuk përmenden kurrë në bajtet që merr dikush tjetër.
subject	jo	Si parazgjedhje, bosh.
html, text	njëra prej tyre	Që të dyja bashkë është në rregull. HTML-ja është ajo që shohin marrësit.
template	njëra prej tyre	`{ id, version?, props?, slots? }`. Një trup i ruajtur, sipas id-së ose slug-ut. Refuzohet bashkë me html, text ose `draftId`. Shihni «Dërgoni me një shabllon».
replyTo	jo	Një adresë e vetme.
headers	jo	`X-`, `List-`, Reply-To, Precedence, Auto-Submitted, Importance, Priority, Feedback-Id.
attachments	jo	`{ filename, content, contentType }` si base64, 5 MB në total, ose `{ fileId }` që emërton një skedar tashmë në hapësirën e punës. 20 skedarë.
attachmentDelivery	jo	`mime`, `link` ose `auto`. `auto` i kalon skedarët si lidhje sapo ata kalojnë 2 MB te një domen me domen skedarësh aktiv. Si parazgjedhje merr cilësimin e kutisë postare.
threadId	jo	Përgjigjuni brenda një bisede ekzistuese.
draftId	jo	Dërgoni një skicë ekzistuese.
scheduledAt	jo	Çast ose kohëzgjatje ISO. Shihni Planifikimin.
cancellableForSeconds	jo	Një dritare zhbërjeje nga 0 deri në 900 sekonda te një dërgim i menjëhershëm. Refuzohet bashkë me `scheduledAt`, i cili mbetet i anulueshëm derisa niset. Shihni Planifikimin.
signature	jo	`false` e lë nënshkrimin jashtë këtij mesazhi. Përndryshe mesazhi mbart nënshkrimin e adresës nga e cila dërgohet, që është ai i vetë asaj adrese ose përndryshe ai i caktuar për Të gjitha adresat.
tags	jo	Deri në 10 etiketa tuajat. Kthehen si jehonë, kurrë nuk interpretohen.
tracking	jo	`{ opens?, clicks? }`. Secila prej tyre e mbivendos cilësimin për këtë mesazh; lëreni një fushë jashtë dhe ajo gjysmë bie te cilësimi i adresës nga e cila dërgohet, ose përndryshe te Të gjitha adresat, dhe është e ndezur nëse asnjëri prej tyre nuk e ka fikur.
translate	jo	`{ to, from?, subject?, includeOriginal? }`. E dërgon mesazhin në gjuhën e marrësit. Zgjidhet kur pranohet kërkesa, refuzohet bashkë me `draftId`.

Fushat e panjohura refuzohen në vend që të shpërfillen, ndaj një emër i shkruar gabim është një 422 tani e jo një befasi më vonë. Kokat që do të anashkalonin autorizimin e dërguesit (From, Sender, Bcc, Message-ID, Return-Path e të tjera) refuzohen me reserved_header.

Përgjigjja

200 kur mesazhi ka ikur tashmë, 202 kur diçka duhet të ndodhë ende me të. Një thirrës që degëzon sipas kodit të statusit ka të drejtë në të dyja rastet.

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 është identifikuesi i qëndrueshëm që ruani dhe ai mbi të cilin kthehet një ngjarje dërgese, sepse një webhook kthimi e emërton si emailId. messageId është Message-ID sipas RFC 5322 dhe është null derisa të ekzistojë MIME-ja. Mos u lidhni me të: shërbimi i dërgimit e rishkruan atë kokë në dalje, ndaj vlera këtu nuk shfaqet në asnjë raport kthimi apo dërgese dhe një përputhje mbi të nuk ndodh kurrë.

Në gjuhën e marrësit

translate e shkruan mesazhin në gjuhën e dikujt tjetër para se ai të niset. Trupi, dhe subjekti nëse nuk e çaktivizoni, përkthehet në çastin kur kërkesa PRANOHET, që është i njëjti rregull që ndjek template dhe është vendimtar për të njëjtat arsye: një mesazh i planifikuar mbart fjalët që u miratuan e jo çfarëdo që prodhon një model të martën, ndërsa një përkthim që nuk mund të prodhohej e refuzon dërgimin para se të ekzistojë një rresht. Asgjë nuk dorëzohet në një gjuhë që dërguesi i saj nuk e zgjodhi.

translate

tostringe detyrueshme: Gjuha në të cilën do të shkruhet: një kod BCP-47 (`de`), një emër anglisht («German») ose emri që gjuha i jep vetes («Deutsch»), nga 2 deri në 60 karaktere. Të tria normalizohen te kodi i tabelës para çdo gjëje tjetër, kështu që janë një kërkesë e vetme — gjë që ka rëndësi, sepse gjurma e Idempotency-Key merret mbi kërkesën e analizuar. Zgjidhen edhe aliasët: `zh-TW` bëhet `zh-Hant`. Një vlerë që nuk zgjidhet në asgjë është një 422 mbi `translate.to`.
fromstring: Gjuha në të cilën e shkruat ju, në cilëndo nga të njëjtat tri forma. Thjesht një optimizim. Nëse lihet jashtë, trupi lexohet dhe gjuha përcaktohet, gjë që kushton një thirrje të shkurtër modeli. Ia vlen ta deklaroni në një rrugë me volum të lartë, dhe ia vlen ta deklaroni kur trupi është kryesisht emra, numra dhe lidhje: zbulimi përmbahet në vend që të hamendësojë, dhe një burim i papërcaktuar nuk ju kushton asgjë veç gjuhës së emërtuar në titullin mbi origjinalin tuaj. Nuk është `from` i nivelit të parë, i cili është një adresë.
subjectboolean: Përkthe edhe rreshtin e subjektit. Si parazgjedhje true; false e dërgon subjektin saktësisht siç e shkruat.
includeOriginalboolean: Vendos atë që shkruat në të vërtetë poshtë përkthimit, pas një ndarësi dhe me një titull në gjuhën e marrësit. Si parazgjedhje true, dhe ia vlen ta lini të ndezur. Është e vetmja gjë që i lejon personit që lexon të kontrollojë një fjali që tingëllon çuditshëm, në vend që t’i kërkohet t’i besojë një modeli daljen e të cilit askush nga ju të dy nuk e sheh dot.

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 është shtesë dhe shfaqet vetëm te një mesazh që u përkthye: në këtë përgjigje dhe te GET /emails/{id}, kurrë te një rresht liste, sepse një listë nuk e merr kërkesën e ruajtur dhe heshtja e saj atje nuk thotë asgjë në asnjë drejtim. Ajo mbart kode e jo rreshta të tërë gjuhësh: është një regjistrim i asaj që u bë, ndërsa GET /languages është vendi ku rri endonimi. subject te përgjigjja është ai i përkthyeri, kështu që një konsolë nuk e rendit kurrë një mesazh nën një varg që marrësi nuk e pa kurrë.

Funksionon me template, dhe ky është rasti i dobishëm: përkthehet dalja E RENDERUAR, ndaj një trup i vetëm i ruajtur u shërben të gjitha gjuhëve në të cilat lexojnë klientët tuaj. Një shabllon që renderon një dokument të tërë çmontohet më parë: te modeli shkon vetëm ajo që ndodhet brenda <body>, ndërsa doctype-i, blloqet <style> dhe rregullat @font-face i rivendosen rreth përgjigjes. Kjo është edhe arsyeja pse kufiri prej 30.000 karakteresh mat prozën e jo dokumentin: një mesazh me dy rreshta i mbështjellë në një fletë stili të markës mbetet një mesazh me dy rreshta.
Pjesa e vetme e një shablloni që mbetet e papërkthyer është <title> i tij, të cilin nuk e shfaq asnjë klient poste. Një <Preview> i react-email renderohet brenda trupit dhe përkthehet bashkë me pjesën tjetër.
Refuzohet bashkë me draftId: një 422 mbi translate, me tekstin «A draft is sent as it was written; translate a body or send a draft, not both». Një skicë është shkruar nga një person dhe dërgohet ashtu siç e la ai.
Qëllimisht nuk është pjesë e gjurmës së idempotencës. Ajo që hash-ohet është kërkesa që dërguat, përfshirë translate; ajo që prodhoi modeli nuk hash-ohet. Kështu, riprovimi i një dërgimi të papërgjigjur me të njëjtin Idempotency-Key e riluan origjinalin. Kthehet mesazhi që ekziston tashmë, pa një dërgim të dytë dhe pa një përkthim të dytë. Hash-imi i formulimit në vend të kësaj do të bënte që një riprovim i ndershëm të prodhonte gjurmë të ndryshme çdo herë — dhe kështu i njëjti mesazh del dy herë.
Një mesazh i përkthyer që është në radhë ose i planifikuar është i ngrirë ndaj ndryshimeve të formulimit. Zhvendoseni ose anulojeni; ndryshimi i asaj që thotë do të thotë ta anuloni dhe ta dërgoni sërish, përpara dikujt që mund t’i lexojë fjalët e reja.
Një gjuhë e synuar nga e djathta në të majtë prodhohet nga e djathta në të majtë: përkthimi mbështillet me dir="rtl", ndërsa origjinali juaj poshtë tij orientohet më vete. Atributi i mbijeton pastruesit dalës, i cili e lejon dir pikërisht për këtë arsye, kështu që mesazhi në rrjet mbart drejtimin që tregoi parapamja.

Kodi	Statusi	Kur
`invalid_parameter`	422	`translate.to` ose `translate.from` emërton një gjuhë që nuk e vendosim dot. Mesazhi thotë cilat tri forma pranohen dhe drejton te `GET /languages`.
`unknown_language`	422	I njëjti dështim, i kapur një hap më vonë, nga shërbimi e jo nga skema. Një rrjetë sigurie, mbi `translate.to`.
`translation_too_long`	422	Mbi 30.000 karaktere në njërin skaj të thirrjes së modelit. Një refuzim e jo një cungim: gjysma e një mesazhi të përkthyer nuk ka asnjë vijë që të tregojë ku ndaloi, dhe personi që lexon vepron mbi gjysmën që iu dha.
`translation_not_configured`	409	Hapësira e punës nuk ka çelës AI dhe AI-ja e platformës është e fikur. Një 409 e jo një 503, sepse riprovimi dështon njësoj. Asgjë nuk u dërgua. Dërgojeni pa `translate` nëse e kishit fjalën ta dërgonit ashtu siç është shkruar.
`translation_failed`	503	Ofruesi nuk u përgjigj, ose u përgjigj me diçka të papërdorshme. Asgjë nuk u dërgua; mesazhi nuk postohet kurrë i papërkthyer si zgjidhje rezervë. Ky dështim është yni dhe ia vlen të riprovohet.
`unknown_parameter`	422	Një çelës i panjohur brenda `translate`, i cili është objekt i rreptë si pjesa tjetër e kërkesës.

Një dërgim nga kodi nuk ka njeri që ta lexojë përkthimin më parë. POST /emails/translate është i njëjti udhëtim, i ndalur një hap më herët, për t’i treguar një personi çfarë është gati të dërgojë. Pastaj dërgoni atë që ai miratoi si një html/subject të zakonshëm, pa asnjë translate te kërkesa.