SDK

Envia un lot

`emails.sendBatch`: fins a 100 missatges, amb resultats per element.

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 conté una entrada per element d'entrada, en ordre, cadascuna amb ok i el seu missatge o amb error i el sobre amb què s'hauria rebutjat aquell missatge. No es desfà res, de manera que failed > 0 és una llista sobre la qual actuar i no pas un motiu per reenviar el lot.

Una sola clau d'idempotència cobreix el lot i el servidor l'estén per element, de manera que un lot reintentat reprodueix tots els missatges en comptes de col·lapsar-los sobre el primer.

Paràmetres: emails.sendBatch

emailsEmailSend[]obligatori: D'un a 100 missatges, serialitzats com a `{ "emails": [...] }` i acceptats d'un en un en l'ordre indicat. Un array buit, més de 100, o més de 10 elements que portin `translate` fan rebutjar tota la crida amb un `validation_error` a `emails`. També ho fan la manca de l'scope `emails:send`, un cos que no sigui ni un array ni `{ emails: [...] }`, i una `Idempotency-Key` mal formada, tots ells abans d'enviar cap missatge.
options.idempotencyKeystring: Desduplica el lot entre processos. El client adjunta de totes maneres una clau generada de nou a cada crida, de manera que els seus propis reintents mai no envien dues vegades, i el servidor estén la clau que rebi per element com a `key/0`, `key/1` i així successivament, separades per una barra, un caràcter que la teva clau no pot contenir, de manera que una sola clau per a cent missatges no els pot col·lapsar sobre el primer.
emails[].fromRecipientInputobligatori: El remitent, com a adreça nua, `Name <addr@host>` o un objecte. No hi ha cap remitent de reserva i la clau ha de tenir permís per a aquesta adreça; un rebuig fa fallar només aquell element, com un `permission_error` amb el codi `from_address_forbidden`.
emails[].toRecipientInput | RecipientInput[]obligatori: Com a mínim un destinatari, i el client n'embolcalla un de sol dins d'un array. Com a màxim 50 adreces entre `to`, `cc` i `bcc` sumats, comptades per missatge i no pas per tot el lot.
emails[].ccRecipientInput | RecipientInput[]: Per defecte no n'hi ha cap, i compta per al mateix total de 50 adreces que `to` i `bcc`.
emails[].bccRecipientInput | RecipientInput[]: Per defecte no n'hi ha cap, i compta per al mateix total de 50 adreces. `Bcc` és un dels noms que `headers` no pot definir, de manera que aquesta és l'única manera de fer una còpia oculta. La forma de capçalera desfaria el sobre per destinatari que manté l'adreça oculta.
emails[].replyToRecipientInput: On van les respostes. S'aplica després de `headers`, de manera que sobreescriu un `Reply-To` que també hi hagis definit en comptes d'afegir-ne un segon.
emails[].subjectstring: Com a màxim 998 caràcters, el límit de línia de l'RFC 5322, i per defecte una cadena buida. Un assumpte buit passa a ser el de la plantilla quan `template` en proporciona un.
emails[].htmlstring: La part HTML, de com a màxim un milió de caràcters, i la part que veuen els destinataris quan s'indiquen els dos cossos. Cal un d'aquests: `html`, `text`, `template` o `draftId`, i un element que no en tingui cap falla com un `validation_error` a `html`.
emails[].textstring: La part de text pla, de com a màxim un milió de caràcters. Es poden enviar totes dues, i tots els transports d'aquest camí construeixen un sol cos a partir d'una sola cadena, de manera que `html` guanya quan n'hi ha.
emails[].headersRecord<string, string>: Només `X-*`, `List-*`, Reply-To, Precedence, Auto-Submitted, Importance, Priority i Feedback-ID; tot allò que el transport defineix ell mateix (From, To, Bcc, Subject, Message-ID, les capçaleres DKIM i ARC) es rebutja com a `reserved_header` en comptes de descartar-se en silenci. Els valors fan com a màxim 998 caràcters i no poden portar CR, LF ni NUL, perquè una segona línia és una segona capçalera.
emails[].attachmentsAttachmentInput[]: Com a màxim 20 fitxers per missatge, amb un total de 5 MB de fitxers inline un cop descodificats, comptats per missatge i no pas per lot. `content` va en base64 pel cable; passa-hi bytes i el client els codifica, que és l'únic lloc on un base64 fet a mà rebenta la pila de crides de manera fiable. Una entrada `{ fileId }` anomena un fitxer que ja és a l'espai de treball i no compta per al límit d'inline.
emails[].threadIdstring: Respon dins d'una conversa existent, amb un màxim de 256 caràcters. El transport hi escriu In-Reply-To i References, que és el que fa que la resposta caigui dins de la conversa i no pas al costat.
emails[].draftIdstring: Envia el contingut d'un esborrany desat amb aquest sobre, amb un màxim de 256 caràcters. Els destinataris, l'assumpte i les capçaleres que es construeixen aquí són el que va pel cable.
emails[].template{ id, version?, props?, slots? }: Renderitza una plantilla desada al servidor, per id (`tpl_…`) o per slug, amb `version` fixant una revisió i `props`/`slots` omplint-la. Es resol un sol cop, quan s'accepta l'element, i es rebutja al costat d'`html`/`text` i al costat de `draftId`, ja que cadascun d'aquests és una segona resposta a què conté el missatge.
emails[].scheduledAtDate | string: Un `Date`, un instant ISO-8601 o una durada com ara `PT1H`; com a mínim un segon en el futur i com a màxim d'aquí a 365 dies. Els elements es programen de manera independent, de manera que un lot pot contenir cent hores d'enviament diferents.
emails[].cancellableForSecondsnumber: Una finestra per desfer, en segons, en un enviament immediat: un integer de 0 a 900, amb 0 per defecte. Qualsevol valor superior a 0 es rebutja al costat de `scheduledAt` en el mateix element, ja que un missatge programat ja es pot cancel·lar fins que surt.
emails[].trackingTrackingRequest: `opens` i `clicks`, cadascun opcional de manera independent i cadascun substituint la configuració només per a aquest missatge. Un interruptor que ometis recorre a la configuració de l'adreça des de la qual s'envia el missatge, o si no a la de Totes les adreces, que està activada tret que una d'aquestes l'hagi desactivada.
emails[].tagsRecord<string, string>: Com a màxim 10 etiquetes, amb claus d'1 a 64 caràcters tretes de `A-Za-z0-9_-` i valors de fins a 256. Es retornen al missatge i no s'interpreten mai: `emails.list` accepta `status`, `from`, `limit` i `cursor` i res més, de manera que una etiqueta és una cosa per llegir d'un missatge que ja tens i no pas una manera de trobar-lo.
emails[].translateSendTranslateOptions: Envia aquest element en un altre idioma, resolt en el moment d'acceptar-lo perquè les paraules aprovades siguin les paraules que surten. Com a màxim 10 elements d'un mateix lot el poden portar: cadascun gasta diverses crides al model i els elements s'executen en ordre, de manera que un lot més gran es mataria a mitja tramesa. Per sobre d'això, tota la crida es rebutja com a `too_many_items` a `emails`, abans d'enviar res.

Resposta: BatchResultResource

itemsBatchItemResource[]: Una entrada per element enviat, en l'ordre en què els has enviat. No es desfà res, de manera que això és un registre del que ha passat a cada missatge i no pas un informe sobre una transacció. L'API respon 207 tant si s'han acceptat tots els missatges com si se n'han acceptat alguns o cap, així que la promesa es resol igualment i és l'`status` de cada element el que cal mirar per ramificar.
sentnumber: Quants elements s'han ACCEPTAT, que no és el mateix que quants han sortit. Un element pot ser `ok` i encara portar un `email.status` de `failed` o `partial`, perquè un transport que rebutja el missatge després que la fila existeixi és un resultat de lliurament i no pas una sol·licitud rebutjada.
failednumber: Quantes entrades porten un `error`. `failed > 0` és una llista sobre la qual actuar i no pas un motiu per reenviar el lot. Els missatges acceptats ja han sortit.
items[].indexnumber: La posició que el missatge d'aquesta entrada ocupava a l'array que has enviat. Va com a camp a més de com a ordre, de manera que el codi que filtra o ordena `items` encara pot dir quin element d'entrada ha fallat.
items[].status'ok' | 'error': El discriminant de la unió: `ok` porta `email`, `error` porta `error`, i cap entrada no porta totes dues coses.
items[].emailSentEmailResource: El missatge acceptat, només en una entrada `ok`, amb la mateixa forma que retorna un enviament individual. No porta cap clau `tracking`, perquè la interacció s'informa més tard i en el moment d'acceptar-lo no hi ha res a informar.
items[].email.replayedboolean: Cert quan la `Idempotency-Key` derivada ha coincidit amb un enviament que ja existia, de manera que no s'ha enviat res de nou i aquest és el missatge original.
items[].error{ type: string; code: string; message: string; param?: string }: Per què s'ha rebutjat aquest missatge concret, només en una entrada `error`. És el sobre d'error de l'API sense `docUrl` ni `requestId`: aquests descriuen la sol·licitud, i la sol·licitud en conjunt ha reeixit.
items[].error.typestring: La categoria segons la qual un client pot ramificar: `validation_error`, `permission_error`, `not_found_error`, `conflict_error` i la resta. El conjunt està congelat i no creixerà, a diferència de `code`.
items[].error.codestring: La fallada concreta: `from_address_forbidden`, `invalid_email_address`, `too_many_recipients`, `reserved_header`, `message_too_large`, `unknown_parameter`. És oberta i additiva, així que tracta un codi que no reconeguis segons el seu `type`.
items[].error.messagestring: Una frase escrita per a una persona, que anomena el valor problemàtic quan n'hi ha. No és un identificador estable. Fes el switch amb `code`.
items[].error.paramstring: El camp que s'ha rebutjat, com un camí amb punts dins d'AQUELL missatge: `to.0`, `from`, `attachments`. Absent quan la fallada no anomena cap camp, i mai prefixat amb la posició dins del lot, per a la qual ja hi ha `index`.