SDK

Köteg küldése

`emails.sendBatch`: legfeljebb 100 üzenet, elemenkénti eredménnyel.

emails.sendBatch

send-batch.ts

const result = await openemail.emails.sendBatch(invoices.map(toMessage)) console.log(result.sent, 'sent,', result.failed, 'failed') for (const item of result.items) {  if (item.status === 'error') console.error(item.index, item.error.code, item.error.message)  else console.log(item.index, item.email.id)}

Az items minden bemenethez egy bejegyzést tartalmaz, sorrendben, amely vagy ok a hozzá tartozó üzenettel, vagy error azzal a hibaborítékkal, amellyel az üzenetet elutasítottuk volna. Semmi nem gördül vissza, így a failed > 0 teendők listája, nem pedig ok a köteg újraküldésére.

Egy idempotenciakulcs fedi a köteget, a kiszolgáló pedig elemenként kiterjeszti, így az újraküldött köteg minden üzenetet visszajátszik, nem pedig mindet az elsőre húzza össze.

Paraméterek: emails.sendBatch

emailsEmailSend[]kötelező: Egy és 100 közötti számú üzenet, `{ "emails": [...] }` formában szerializálva, egyesével, a megadott sorrendben feldolgozva. Az üres tömb, a 100-nál több elem, vagy a 10-nél több `translate` értéket hordozó elem az egész hívást `validation_error` hibával utasítja el az `emails` mezőn. Ugyanígy a hiányzó `emails:send` hatókör, a nem tömb és nem `{ emails: [...] }` alakú törzs, valamint a hibás `Idempotency-Key` – mindegyik még azelőtt, hogy egyetlen üzenet is elment volna.
options.idempotencyKeystring: Folyamatok között is deduplikálja a köteget. A kliens minden híváson amúgy is frissen generált kulcsot csatol, így a saját újrapróbálkozásai soha nem küldenek kétszer, a kiszolgáló pedig a kapott kulcsot elemenként kiterjeszti `key/0`, `key/1` és így tovább formában, perjellel elválasztva, olyan karakterrel, amely a saját kulcsodban nem szerepelhet, így egy kulcs száz üzeneten át sem tudja mindet az elsőre összehúzni.
emails[].fromRecipientInputkötelező: A feladó, csupasz címként, `Name <addr@host>` formában vagy objektumként. Nincs tartalék feladó, és a kulcsnak engedélyezve kell lennie erre a címre; az elutasítás azt az egy elemet buktatja el `permission_error` típussal és `from_address_forbidden` kóddal.
emails[].toRecipientInput | RecipientInput[]kötelező: Legalább egy címzett, az egyedülállót pedig a kliens tömbbe csomagolja. A `to`, a `cc` és a `bcc` együtt legfeljebb 50 címet tartalmazhat, üzenetenként és nem a kötegre összesítve számolva.
emails[].ccRecipientInput | RecipientInput[]: Alapértelmezés szerint nincs, és ugyanabba az 50 címes keretbe számít bele, mint a `to` és a `bcc`.
emails[].bccRecipientInput | RecipientInput[]: Alapértelmezés szerint nincs, és ugyanabba az 50 címes keretbe számít bele. A `Bcc` egyike azoknak a neveknek, amelyeket a `headers` nem állíthat be, így ez az egyetlen mód a titkos másolatra. A fejléces forma felülírná azt a címzettenkénti borítékot, amely a címet titokban tartja.
emails[].replyToRecipientInput: Ide mennek a válaszok. A `headers` után alkalmazzuk, így felülírja az ott esetleg beállított `Reply-To` fejlécet, nem pedig egy másodikat ad hozzá.
emails[].subjectstring: Legfeljebb 998 karakter, az RFC 5322 sorhossz-korlátja, alapértelmezés szerint üres sztring. Az üres tárgy helyére a sablon sajátja kerül, ha a `template` ad egyet.
emails[].htmlstring: A HTML rész, legfeljebb egymillió karakter, és ez az, amit a címzettek látnak, ha mindkét törzset megadod. A `html`, a `text`, a `template` vagy a `draftId` közül egy kötelező, és az az elem, amelyen egyik sincs, `validation_error` hibával bukik el a `html` mezőn.
emails[].textstring: Az egyszerű szöveges rész, legfeljebb egymillió karakter. Mindkettő elküldhető, és ezen az útvonalon minden szállítás egyetlen sztringből építi az egyetlen törzset, így a `html` nyer, ha van.
emails[].headersRecord<string, string>: Csak `X-*`, `List-*`, Reply-To, Precedence, Auto-Submitted, Importance, Priority és Feedback-ID; bármit, amit a szállítás maga állít be (From, To, Bcc, Subject, Message-ID, a DKIM- és ARC-fejlécek), `reserved_header` hibával utasítunk el, nem pedig csendben eldobunk. Az értékek legfeljebb 998 karakteresek, és nem tartalmazhatnak CR, LF vagy NUL karaktert, mert a második sor már második fejléc.
emails[].attachmentsAttachmentInput[]: Üzenetenként legfeljebb 20 fájl, a beágyazott fájlok dekódolva összesen 5 MB méretig, üzenetenként és nem kötegenként számolva. A `content` a hálózaton base64; add át a bájtokat, és a kliens kódolja – ez az egyetlen hely, ahol a kézzel írt base64 megbízhatóan szétveti a hívásvermet. A `{ fileId }` bejegyzés a munkaterületen már meglévő fájlt nevez meg, és nem számít bele a beágyazott korlátba.
emails[].threadIdstring: Válasz egy meglévő beszélgetésbe, legfeljebb 256 karakter. A szállítás ebből írja az In-Reply-To és a References fejlécet, és ettől kerül a válasz a beszélgetésbe, nem mellé.
emails[].draftIdstring: Egy mentett piszkozat tartalmának küldése ezzel a borítékkal, legfeljebb 256 karakter. A hálózatra az itt felépített címzettek, tárgy és fejlécek kerülnek.
emails[].template{ id, version?, props?, slots? }: Tárolt sablon kiszolgálóoldali renderelése azonosító (`tpl_…`) vagy slug alapján, ahol a `version` rögzíti a revíziót, a `props`/`slots` pedig kitölti. Egyszer, az elem elfogadásakor oldódik fel, és a `html`/`text`, illetve a `draftId` mellett elutasítjuk, mivel ezek mindegyike egy-egy további válasz arra, hogy mit tartalmaz az üzenet.
emails[].scheduledAtDate | string: Egy `Date`, egy ISO-8601 időpont, vagy egy időtartam, például `PT1H`; legalább egy másodperccel a jövőben és legfeljebb 365 nappal előre. Az elemek egymástól függetlenül ütemeződnek, így egy köteg akár száz különböző küldési időt is tartalmazhat.
emails[].cancellableForSecondsnumber: Visszavonási ablak másodpercben egy azonnali küldésen, 0 és 900 közötti egész szám, alapértelmezés szerint 0. A 0-nál nagyobb értéket ugyanazon az elemen a `scheduledAt` mellett elutasítjuk, mivel az ütemezett üzenet a küldésig amúgy is visszavonható.
emails[].trackingTrackingRequest: Az `opens` és a `clicks` egymástól függetlenül opcionális, és mindegyik csak erre az üzenetre írja felül a beállítást. A kihagyott kapcsoló annak a címnek a beállítására esik vissza, amelyről az üzenet megy, annak hiányában pedig az Összes címre vonatkozóra, ami bekapcsolt, hacsak valamelyik ki nem kapcsolta.
emails[].tagsRecord<string, string>: Legfeljebb 10 címke, ahol a kulcsok 1–64 karakteresek az `A-Za-z0-9_-` készletből, az értékek pedig legfeljebb 256 karakteresek. Az üzeneten visszakapod őket, és soha nem értelmezzük: az `emails.list` a `status`, a `from`, a `limit` és a `cursor` paramétert fogadja, mást nem, így a címke olyasmi, amit egy már kézben tartott üzenetről olvasol le, nem pedig keresési eszköz.
emails[].translateSendTranslateOptions: Küldd el ezt az elemet másik nyelven, az elfogadáskor feloldva, hogy a jóváhagyott szavak menjenek ki. Egy kötegben legfeljebb 10 elem hordozhatja: mindegyik több modellhívást fogyaszt, és az elemek sorban futnak, így egy nagyobb köteget küldés közben leállítana a rendszer. Ezen felül az egész hívást `too_many_items` hibával utasítjuk el az `emails` mezőn, még azelőtt, hogy bármi elment volna.

Válasz: BatchResultResource

itemsBatchItemResource[]: Bemenetenként egy bejegyzés, a küldés sorrendjében. Semmi nem gördül vissza, ezért ez annak a feljegyzése, hogy mi történt az egyes üzenetekkel, nem pedig tranzakciós jelentés. Az API 207-tel válaszol akkor is, ha minden üzenetet elfogadtunk, akkor is, ha csak néhányat, és akkor is, ha egyet sem, így a promise mindenképp teljesül, és az elemenkénti `status` az, amire ágazni kell.
sentnumber: Hány elemet FOGADTUNK EL, ami nem ugyanaz, mint hogy hány ment el. Egy elem lehet `ok` úgy is, hogy az `email.status` értéke `failed` vagy `partial`, mert ha a szállítás a sor létrejötte után utasítja el az üzenetet, az kézbesítési eredmény, nem elutasított kérés.
failednumber: Hány bejegyzés hordoz `error` mezőt. A `failed > 0` teendők listája, nem pedig ok a köteg újraküldésére. Az elfogadott üzenetek már elmentek.
items[].indexnumber: Az a pozíció, amelyet ennek a bejegyzésnek az üzenete az általad küldött tömbben elfoglalt. A sorrend mellett mezőként is hordozzuk, hogy az `items` listát szűrő vagy rendező kód is meg tudja mondani, melyik bemenet bukott el.
items[].status'ok' | 'error': Az unió megkülönböztetője: az `ok` az `email` mezőt hordozza, az `error` az `error` mezőt, és egyetlen bejegyzésen sincs ott mindkettő.
items[].emailSentEmailResource: Az elfogadott üzenet, kizárólag `ok` bejegyzésen, ugyanabban az alakban, amelyet az egyszeri küldés ad vissza. Nem hordoz `tracking` kulcsot, mert az elköteleződésről később számolunk be, és elfogadáskor nincs miről.
items[].email.replayedboolean: Igaz, ha a származtatott `Idempotency-Key` egy már létező küldéssel egyezett, tehát semmi új nem ment el, és ez az eredeti üzenet.
items[].error{ type: string; code: string; message: string; param?: string }: Miért utasítottuk el ezt az egy üzenetet, kizárólag `error` bejegyzésen. Ez az API hibaborítéka a `docUrl` és a `requestId` nélkül: azok a kérést írják le, a kérés egésze pedig sikeres volt.
items[].error.typestring: A kategória, amelyre a kliens elágazhat: `validation_error`, `permission_error`, `not_found_error`, `conflict_error` és a többi. A halmaz zárt, és nem fog bővülni, szemben a `code` mezővel.
items[].error.codestring: A konkrét hiba: `from_address_forbidden`, `invalid_email_address`, `too_many_recipients`, `reserved_header`, `message_too_large`, `unknown_parameter`. Nyitott és bővíthető, ezért az ismeretlen kódot a `type` mezője szerint kezeld.
items[].error.messagestring: Egy mondat, embernek írva, megnevezve a kifogásolt értéket, ha van ilyen. Nem stabil azonosító. A `code` mezőre ágazz el.
items[].error.paramstring: Az elutasított mező, pontokkal tagolt útvonalként AZON AZ ÜZENETEN belül: `to.0`, `from`, `attachments`. Hiányzik, ha a hiba nem nevez meg mezőt, és soha nincs elé fűzve a kötegbeli pozíció – arra való az `index`.