SDK

Een batch versturen

`emails.sendBatch`: maximaal 100 berichten, resultaten per item.

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)}

items bevat één item per invoer, in volgorde, elk ofwel ok met het bericht ofwel error met de envelop waarmee dat bericht geweigerd zou zijn. Er wordt niets teruggedraaid, dus failed > 0 is een lijst om naar te handelen en geen reden om de batch opnieuw te versturen.

Eén idempotency-sleutel dekt de batch en de server breidt die per item uit, dus een herhaalde batch speelt elk bericht opnieuw af in plaats van ze op het eerste samen te vouwen.

Parameters: emails.sendBatch

emailsEmailSend[]verplicht: Eén tot 100 berichten, geserialiseerd als `{ "emails": [...] }` en één voor één geaccepteerd in de gegeven volgorde. Een lege array, meer dan 100, of meer dan 10 items met `translate` weigert de hele aanroep met een `validation_error` op `emails`. Hetzelfde geldt voor een ontbrekende `emails:send`-scope, een body die geen array of `{ emails: [...] }` is, en een misvormde `Idempotency-Key`, allemaal voordat er één bericht verstuurd is.
options.idempotencyKeystring: Ontdubbelt de batch over processen heen. De client hangt sowieso bij elke aanroep een vers gegenereerde sleutel mee, dus zijn eigen herhalingen versturen nooit dubbel, en de server breidt de sleutel die hij krijgt per item uit als `key/0`, `key/1` enzovoort, gescheiden door een slash — een teken dat je eigen sleutel niet mag bevatten — zodat één sleutel over honderd berichten ze niet op het eerste kan samenvouwen.
emails[].fromRecipientInputverplicht: De afzender, als kaal adres, `Name <addr@host>` of een object. Er is geen terugvalafzender en de sleutel moet dit adres mogen gebruiken; een weigering laat dat ene item falen, als een `permission_error` met code `from_address_forbidden`.
emails[].toRecipientInput | RecipientInput[]verplicht: Minstens één ontvanger, en een enkele wordt door de client in een array gewikkeld. Maximaal 50 adressen over `to`, `cc` en `bcc` samen, geteld per bericht en niet over de batch.
emails[].ccRecipientInput | RecipientInput[]: Standaard geen, en telt mee voor hetzelfde totaal van 50 adressen als `to` en `bcc`.
emails[].bccRecipientInput | RecipientInput[]: Standaard geen, en telt mee voor hetzelfde totaal van 50 adressen. `Bcc` is een van de namen die `headers` niet mag instellen, dus dit is de enige manier om blind te kopiëren. De headervorm zou de envelop per ontvanger ongedaan maken die het adres blind houdt.
emails[].replyToRecipientInput: Waar antwoorden heen gaan. Dit wordt na `headers` toegepast, dus het overschrijft een `Reply-To` die je daar ook hebt gezet in plaats van er een tweede aan toe te voegen.
emails[].subjectstring: Maximaal 998 tekens, de regellimiet uit RFC 5322, en standaard een lege string. Een leeg onderwerp valt door naar dat van het sjabloon wanneer `template` er een levert.
emails[].htmlstring: Het HTML-deel, maximaal een miljoen tekens, en het deel dat ontvangers zien wanneer beide bodies gegeven zijn. Een van `html`, `text`, `template` of `draftId` is verplicht, en een item met geen daarvan faalt als een `validation_error` op `html`.
emails[].textstring: Het platte-tekstdeel, maximaal een miljoen tekens. Beide mogen verstuurd worden, en elk transport op dit pad bouwt één body uit één string, dus `html` wint waar die er is.
emails[].headersRecord<string, string>: Alleen `X-*`, `List-*`, Reply-To, Precedence, Auto-Submitted, Importance, Priority en Feedback-ID; alles wat het transport zelf instelt (From, To, Bcc, Subject, Message-ID, de DKIM- en ARC-headers) wordt geweigerd als `reserved_header` in plaats van stilletjes weggelaten. Waarden zijn maximaal 998 tekens en mogen geen CR, LF of NUL bevatten, want een tweede regel is een tweede header.
emails[].attachmentsAttachmentInput[]: Maximaal 20 bestanden per bericht, waarbij inline bestanden samen 5 MB mogen zijn na decodering, geteld per bericht en niet per batch. `content` is base64 op de lijn; geef bytes mee en de client codeert ze, wat de ene plek is waar zelfgeschreven base64 betrouwbaar de call stack opblaast. Een `{ fileId }`-item noemt een bestand dat al in de workspace staat en telt niet mee voor de inline-limiet.
emails[].threadIdstring: Antwoord binnen een bestaande thread, maximaal 256 tekens. Het transport schrijft In-Reply-To en References hieruit, en dat is wat het antwoord in het gesprek laat landen in plaats van ernaast.
emails[].draftIdstring: Verstuur de inhoud van een opgeslagen concept onder deze envelop, maximaal 256 tekens. De ontvangers, het onderwerp en de headers die hier opgebouwd worden gaan over de lijn.
emails[].template{ id, version?, props?, slots? }: Render een opgeslagen sjabloon aan de serverkant, op id (`tpl_…`) of slug, waarbij `version` een revisie vastpint en `props`/`slots` het vullen. Eenmaal opgelost, wanneer het item wordt geaccepteerd, en geweigerd naast `html`/`text` en naast `draftId`, aangezien elk daarvan een tweede antwoord is op de vraag wat het bericht bevat.
emails[].scheduledAtDate | string: Een `Date`, een ISO-8601-tijdstip, of een duur zoals `PT1H`; minstens een seconde in de toekomst en hoogstens 365 dagen vooruit. Items plannen onafhankelijk van elkaar, dus één batch kan honderd verschillende verzendtijden bevatten.
emails[].cancellableForSecondsnumber: Een ongedaan-maken-venster in seconden bij een directe verzending, een integer van 0 tot 900, standaard 0. Alles boven 0 wordt geweigerd naast `scheduledAt` op hetzelfde item, aangezien een gepland bericht al annuleerbaar is tot het weggaat.
emails[].trackingTrackingRequest: `opens` en `clicks`, elk onafhankelijk optioneel en elk de instelling voor alleen dit bericht overschrijvend. Een schakelaar die je weglaat valt terug op de instelling van het adres waarvandaan het bericht verstuurd wordt, of anders op Alle adressen, wat aan staat tenzij een van die twee het heeft uitgezet.
emails[].tagsRecord<string, string>: Maximaal 10 labels, sleutels van 1 tot 64 tekens uit `A-Za-z0-9_-` en waarden tot 256. Worden op het bericht teruggegeven en nooit geïnterpreteerd: `emails.list` accepteert `status`, `from`, `limit` en `cursor` en verder niets, dus een tag is iets om af te lezen van een bericht dat je al hebt en geen manier om er een te vinden.
emails[].translateSendTranslateOptions: Verstuur dit item in een andere taal, opgelost op het moment van accepteren zodat de woorden die zijn goedgekeurd de woorden zijn die uitgaan. Maximaal 10 items in één batch mogen dit dragen: elk kost meerdere modelaanroepen en de items draaien op volgorde, dus een grotere batch zou halverwege het verzenden afgebroken worden. Daarboven wordt de hele aanroep geweigerd als `too_many_items` op `emails`, voordat er iets verstuurd is.

Antwoord: BatchResultResource

itemsBatchItemResource[]: Eén item per invoer, in de volgorde waarin je ze stuurde. Er wordt niets teruggedraaid, dus dit is een verslag van wat er met elk bericht gebeurde en geen rapport over een transactie. De API antwoordt 207 of nu elk bericht geaccepteerd werd, sommige, of geen enkel, dus de promise lost hoe dan ook op en de `status` per item is waarop je moet vertakken.
sentnumber: Hoeveel items zijn GEACCEPTEERD, wat niet hetzelfde is als hoeveel er zijn vertrokken. Een item kan `ok` zijn en toch een `email.status` van `failed` of `partial` dragen, omdat een transport dat het bericht weigert nadat de rij bestaat een bezorgingsuitkomst is en geen geweigerd verzoek.
failednumber: Hoeveel items een `error` dragen. `failed > 0` is een lijst om naar te handelen en geen reden om de batch opnieuw te versturen. De geaccepteerde berichten zijn al weg.
items[].indexnumber: De positie die het bericht van dit item had in de array die je stuurde. Meegegeven als veld en niet alleen als volgorde, zodat code die `items` filtert of sorteert alsnog kan zeggen welke invoer faalde.
items[].status'ok' | 'error': De discriminant van de union: `ok` draagt `email`, `error` draagt `error`, en geen enkel item draagt beide.
items[].emailSentEmailResource: Het geaccepteerde bericht, alleen op een `ok`-item, in dezelfde vorm als een enkele verzending teruggeeft. Het draagt geen `tracking`-sleutel, omdat betrokkenheid later wordt gerapporteerd en er op het moment van accepteren niets te rapporteren valt.
items[].email.replayedboolean: Waar wanneer de afgeleide `Idempotency-Key` overeenkwam met een verzending die al bestond, dus er is niets nieuws verstuurd en dit is het oorspronkelijke bericht.
items[].error{ type: string; code: string; message: string; param?: string }: Waarom dit ene bericht geweigerd werd, alleen op een `error`-item. Het is de foutenvelop van de API min `docUrl` en `requestId`: die beschrijven het verzoek, en het verzoek als geheel slaagde.
items[].error.typestring: De categorie waarop een client mag vertakken: `validation_error`, `permission_error`, `not_found_error`, `conflict_error` en de rest. De verzameling ligt vast en groeit niet, anders dan `code`.
items[].error.codestring: De specifieke fout: `from_address_forbidden`, `invalid_email_address`, `too_many_recipients`, `reserved_header`, `message_too_large`, `unknown_parameter`. Open en aanvullend, dus behandel een code die je niet herkent als zijn `type`.
items[].error.messagestring: Eén zin geschreven voor een persoon, die de aanstootgevende waarde noemt waar die er is. Geen stabiele identificator. Schakel op `code`.
items[].error.paramstring: Het veld dat geweigerd werd, als een puntpad binnen DAT bericht: `to.0`, `from`, `attachments`. Afwezig wanneer de fout geen veld noemt, en nooit voorafgegaan door de batchpositie, waar `index` voor is.