SDK
Odeslání dávky
`emails.sendBatch`: až 100 zpráv, výsledky po jednotlivých položkách.
emails.sendBatch
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)}items obsahuje jednu položku na každý vstup, ve stejném pořadí, buď ok se zprávou, nebo error s obálkou, kterou by ta zpráva byla odmítnuta. Nic se nevrací zpět, takže failed > 0 je seznam, podle kterého je třeba jednat, ne důvod poslat dávku znovu.
Jeden idempotenční klíč pokrývá celou dávku a server jej rozšíří pro každou položku, takže opakovaná dávka přehraje každou zprávu, místo aby je všechny sloučila do první.
Parametry: emails.sendBatch
emailsEmailSend[]povinné- Jedna až 100 zpráv, serializovaných jako `{ "emails": [...] }` a přijímaných po jedné v zadaném pořadí. Prázdné pole, více než 100 položek nebo více než 10 položek s `translate` odmítne celé volání s `validation_error` na `emails`. Totéž udělá chybějící scope `emails:send`, tělo, které není pole ani `{ emails: [...] }`, a špatně utvořený `Idempotency-Key` – všechno ještě dřív, než odejde jediná zpráva.
options.idempotencyKeystring- Deduplikuje dávku napříč procesy. Klient stejně ke každému volání připojí čerstvě vygenerovaný klíč, takže jeho vlastní opakování nikdy neodešle nic dvakrát, a server klíč, který dostane, rozšíří pro každou položku na `key/0`, `key/1` a tak dále – oddělovačem je lomítko, znak, který váš vlastní klíč obsahovat nesmí, takže jeden klíč nad stovkou zpráv je nemůže sloučit do první.
emails[].fromRecipientInputpovinné- Odesílatel, buď jako holá adresa, `Name <addr@host>`, nebo objekt. Žádný náhradní odesílatel neexistuje a klíč musí mít tuto adresu povolenou; odmítnutí shodí jen tuto jednu položku, jako `permission_error` s kódem `from_address_forbidden`.
emails[].toRecipientInput | RecipientInput[]povinné- Alespoň jeden příjemce; jediného klient zabalí do pole. Nejvýše 50 adres dohromady napříč `to`, `cc` a `bcc`, počítáno na zprávu, ne na celou dávku.
emails[].ccRecipientInput | RecipientInput[]- Výchozí je žádný a započítává se do téhož součtu 50 adres jako `to` a `bcc`.
emails[].bccRecipientInput | RecipientInput[]- Výchozí je žádný a započítává se do téhož součtu 50 adres. `Bcc` je jedno ze jmen, která `headers` nastavit nesmí, takže tohle je jediný způsob, jak poslat skrytou kopii. Hlavičková podoba by zrušila obálku posílanou zvlášť pro každého příjemce, která adresu drží skrytou.
emails[].replyToRecipientInput- Kam mají chodit odpovědi. Uplatní se až po `headers`, takže `Reply-To`, které jste nastavili i tam, přepíše, místo aby přidalo druhé.
emails[].subjectstring- Nejvýše 998 znaků, limit řádku podle RFC 5322, a výchozí je prázdný řetězec. Prázdný předmět propadne k předmětu šablony, pokud jej `template` dodá.
emails[].htmlstring- Část HTML, nejvýše milion znaků, a ta část, kterou příjemci uvidí, když zadáte obě těla. Vyžaduje se jedno z `html`, `text`, `template` nebo `draftId`; položka bez kteréhokoli z nich selže jako `validation_error` na `html`.
emails[].textstring- Část v prostém textu, nejvýše milion znaků. Poslat lze obě a každý transport na této cestě sestavuje jedno tělo z jednoho řetězce, takže tam, kde je `html`, vyhrává ono.
emails[].headersRecord<string, string>- Pouze `X-*`, `List-*`, Reply-To, Precedence, Auto-Submitted, Importance, Priority a Feedback-ID; cokoli, co si nastavuje sám transport (From, To, Bcc, Subject, Message-ID, hlavičky DKIM a ARC), je odmítnuto jako `reserved_header`, ne tiše zahozeno. Hodnoty mají nejvýše 998 znaků a nesmí obsahovat CR, LF ani NUL, protože druhý řádek je druhá hlavička.
emails[].attachmentsAttachmentInput[]- Nejvýše 20 souborů na zprávu, přičemž vložené soubory mají po dekódování dohromady nejvýše 5 MB, počítáno na zprávu, ne na dávku. `content` jde po drátě jako base64; předejte bajty a klient je zakóduje – je to jediné místo, kde ručně psaný base64 spolehlivě přeteče zásobník volání. Položka `{ fileId }` odkazuje na soubor, který už v pracovním prostoru je, a do limitu vložených souborů se nezapočítává.
emails[].threadIdstring- Odpověď do existujícího vlákna, nejvýše 256 znaků. Transport z toho zapíše In-Reply-To a References, což je to, díky čemu odpověď přistane v konverzaci, a ne vedle ní.
emails[].draftIdstring- Odešle obsah uloženého konceptu pod touto obálkou, nejvýše 256 znaků. Po drátě jdou příjemci, předmět a hlavičky sestavené zde.
emails[].template{ id, version?, props?, slots? }- Vykreslí uloženou šablonu na serveru, podle id (`tpl_…`) nebo slugu, kde `version` připíná konkrétní revizi a `props`/`slots` ji naplní. Vyhodnocuje se jednou, při přijetí položky, a je odmítnuta společně s `html`/`text` i s `draftId`, protože každé z nich je druhou odpovědí na otázku, co zpráva obsahuje.
emails[].scheduledAtDate | string- `Date`, okamžik podle ISO-8601 nebo doba trvání jako `PT1H`; nejméně sekundu v budoucnosti a nejvýše 365 dní dopředu. Položky se plánují nezávisle, takže jedna dávka může nést sto různých časů odeslání.
emails[].cancellableForSecondsnumber- Okno pro vzetí zpět v sekundách u okamžitého odeslání, celé číslo od 0 do 900, výchozí 0. Cokoli nad 0 je u téže položky odmítnuto společně se `scheduledAt`, protože naplánovanou zprávu lze stejně zrušit až do chvíle, než odejde.
emails[].trackingTrackingRequest- `opens` a `clicks`, každé nezávisle volitelné a každé přepisující nastavení jen pro tuto zprávu. Přepínač, který vynecháte, se vrátí k nastavení adresy, ze které se zpráva odesílá, případně k nastavení Všechny adresy, které je zapnuté, pokud je jedno z nich nevyplo.
emails[].tagsRecord<string, string>- Nejvýše 10 štítků, klíče o 1 až 64 znacích z `A-Za-z0-9_-` a hodnoty do 256 znaků. U zprávy se vracejí zpět a nikdy se nijak neinterpretují: `emails.list` přijímá `status`, `from`, `limit` a `cursor` a nic jiného, takže štítek je něco, co si přečtete ze zprávy, kterou už máte, ne způsob, jak ji najít.
emails[].translateSendTranslateOptions- Odešle tuto položku v jiném jazyce; vyhodnocuje se při přijetí, takže odejdou přesně ta slova, která byla schválena. V jedné dávce ji smí nést nejvýše 10 položek: každá spotřebuje několik volání modelu a položky se zpracovávají po pořádku, takže větší dávka by byla uprostřed odesílání ukončena. Nad tento počet je celé volání odmítnuto jako `too_many_items` na `emails`, ještě než se cokoli odešle.
Odpověď: BatchResultResource
itemsBatchItemResource[]- Jedna položka na každý vstup, v pořadí, v jakém jste je poslali. Nic se nevrací zpět, takže je to záznam o tom, co se stalo s každou zprávou, ne hlášení o transakci. API odpovídá 207 bez ohledu na to, zda byly přijaty všechny zprávy, jen některé, nebo žádná, takže se promise vyřeší tak jako tak a větvit je třeba podle `status` u jednotlivých položek.
sentnumber- Kolik položek bylo PŘIJATO, což není totéž jako kolik jich odešlo. Položka může být `ok` a přesto nést `email.status` `failed` nebo `partial`, protože transport, který zprávu odmítne až poté, co záznam existuje, je výsledkem doručování, ne odmítnutým požadavkem.
failednumber- Kolik položek nese `error`. `failed > 0` je seznam, podle kterého je třeba jednat, ne důvod poslat dávku znovu. Přijaté zprávy už odešly.
items[].indexnumber- Pozice, kterou zpráva této položky měla v poli, které jste poslali. Nese se nejen pořadím, ale i jako pole, takže kód, který `items` filtruje nebo řadí, pořád dokáže říct, který vstup selhal.
items[].status'ok' | 'error'- Rozlišovač sjednoceného typu: `ok` nese `email`, `error` nese `error` a žádná položka nenese obojí.
items[].emailSentEmailResource- Přijatá zpráva, jen u položky `ok`, ve stejném tvaru, jaký vrací jednotlivé odeslání. Nenese klíč `tracking`, protože interakce se hlásí až později a v okamžiku přijetí není co hlásit.
items[].email.replayedboolean- True, když odvozený `Idempotency-Key` odpovídal odeslání, které už existovalo, takže se nic nového neodeslalo a tohle je původní zpráva.
items[].error{ type: string; code: string; message: string; param?: string }- Proč byla odmítnuta právě tato zpráva, jen u položky `error`. Je to chybová obálka API bez `docUrl` a `requestId`: ty popisují požadavek, a ten jako celek uspěl.
items[].error.typestring- Kategorie, podle které se klient smí větvit: `validation_error`, `permission_error`, `not_found_error`, `conflict_error` a další. Tato množina je zmrazená a nebude růst, na rozdíl od `code`.
items[].error.codestring- Konkrétní chyba: `from_address_forbidden`, `invalid_email_address`, `too_many_recipients`, `reserved_header`, `message_too_large`, `unknown_parameter`. Množina je otevřená a jen se rozšiřuje, takže kód, který neznáte, zpracujte podle jeho `type`.
items[].error.messagestring- Jedna věta psaná pro člověka, která pojmenuje závadnou hodnotu, pokud nějaká je. Není to stabilní identifikátor. Větvete se podle `code`.
items[].error.paramstring- Pole, které bylo odmítnuto, jako tečkovaná cesta uvnitř TÉ zprávy: `to.0`, `from`, `attachments`. Chybí, když chyba žádné pole nepojmenovává, a nikdy není opatřeno prefixem pozice v dávce – od toho je `index`.