SDK
Llista i obtén
`emails.list`, `emails.listAll`, `emails.iterate`, `emails.get` i `emails.listEvents`.
emails.list
const first = await openemail.emails.list({ status: ['queued', 'scheduled'], from: '[email protected]', limit: 50,}) const second = first.nextCursor ? await openemail.emails.list({ status: ['queued', 'scheduled'], limit: 50, cursor: first.nextCursor }) : nullUna pàgina és { items, hasMore, nextCursor }. Torna a passar nextCursor com a cursor, amb els mateixos filtres, per obtenir la pàgina següent.
emails.iterate i emails.listAll
for await (const email of openemail.emails.iterate({ status: 'failed' })) { console.error(email.id, email.lastError)} const failures = await openemail.emails.listAll({ status: 'failed', from: '[email protected]' })Tots dos segueixen nextCursor per tu. iterate baixa una pàgina només quan el bucle hi arriba, de manera que sortir-ne atura les sol·licituds, mentre que listAll recorre totes les pàgines abans de resoldre's en un sol array, així que dona-li un filtre que s'acabi. En tots dos casos la paginació és per keyset, de manera que un missatge que arribi a mitja iteració no pot fer que se salti una fila, com passaria amb un offset.
emails.get i emails.listEvents
const email = await openemail.emails.get('msg_…')console.log(email.status, email.recipients) const events = await openemail.emails.listEvents('msg_…')for (const event of events) console.log(event.type, event.createdAt)get és l'única crida que retorna recipients, una fila per adreça. Una llista de cinquanta missatges cadascun amb els seus destinataris és una pàgina d'informe que ningú no ha demanat.
Paràmetres
statusEmailStatus | EmailStatus[]- Un estat o diversos (`queued`, `scheduled`, `sending`, `sent`, `partial`, `cancelled`, `failed`), amb coincidència amb qualsevol dels indicats. L'SDK envia un array com un sol valor separat per comes perquè el servidor parteix per comes; un valor fora d'aquest conjunt és un 422 que anomena el desconegut.
fromstring- Coincidència exacta amb l'adreça d'enviament tal com es va registrar, que és l'`addr@host` nu en minúscules. La fila s'escriu sense cap nom visible, de manera que una angle-addr com ara `Acme <[email protected]>` no coincideix amb res. El teu valor es passa a minúscules abans de comparar, i és una igualtat i no pas una coincidència per prefix o per domini.
limitnumber- Files en aquesta pàgina, d'1 a 100, amb 25 per defecte. Un valor fora d'aquest rang es rebutja amb un 422 en comptes de retallar-se.
cursorstring- Un id de missatge (`msg_…`) des del qual paginar. És per keyset i no per offset: les files tornen estrictament més antigues que el `createdAt` d'aquell missatge, de manera que els enviaments que arribin a mitja pàgina no poden empènyer cap fila més enllà de tu. Un id que no anomena cap missatge d'aquest espai de treball és un 400.
Resposta: Page<EmailResource>
itemsEmailResource[]- Una pàgina de missatges, del més nou al més antic per `createdAt`, extreta del sobre `data` de l'API. Les files de la llista no porten mai el desglossament `recipients` per adreça. Això és a `get`.
hasMoreboolean- Si hi ha més files que coincideixen amb el filtre més enllà d'aquesta pàgina. Es respon baixant una fila més que `limit` i no pas amb una segona consulta de recompte.
nextCursorstring | null- L'id que cal tornar a passar com a `cursor`, i null a l'última pàgina. `iterate` i `listAll` s'aturen quan això és null o `hasMore` és fals, ja que una pàgina que digui que n'hi ha més sense anomenar cap cursor faria un bucle etern.
items[].object'email'- Sempre `'email'` en una fila d'aquesta llista.
items[].idstring- L'id propi d'aquesta API, `msg_…`. És el que accepten tots els altres endpoints d'emails, i el que anomena un cursor.
items[].statusEmailStatus- En quin punt de la seva vida és el missatge. `partial` és un estat propi i no pas una varietat de `failed`: alguns destinataris ja el tenen i no se'ls pot desenviar, de manera que reintentar és un error.
items[].modeApiKeyMode- `live` o `test`, pres de la clau que el va enviar. Un enviament de prova es registra aquí i no es transmet mai.
items[].fromstring- L'adreça sota la qual es va autoritzar l'enviament, desada nua i en minúscules, de manera que un nom visible indicat a `from` encara surt pel cable però no es desa aquí. És una cadena simple i no pas un objecte perquè aquesta és la identitat que es va autoritzar: una adreça fora de l'abast d'enviament d'una clau, que no sigui ni d'un domini que té ni hi estigui anomenada, es rebutja amb un 403, i mai no se substitueix en silenci per una que sí que hi estigui.
items[].subjectstring | null- L'assumpte tal com està desat. Null en un missatge registrat sense cap.
items[].messageIdstring | null- El Message-ID de l'RFC 5322, no pas el nostre id. Null fins que existeix el MIME, i el servei d'enviament el reescriu a la sortida, de manera que un rebot o un DSN posterior porta un id diferent i es correlaciona amb `items[].id`.
items[].threadIdstring | null- La conversa a la qual pertany aquest missatge, quan se n'hi ha indicat o assignat una. Null en cas contrari.
items[].transportEmailTransport | (string & {}) | null- Com han sortit els bytes. Null fins a la tramesa, i amb un tipus obert perquè un transport que aquest SDK encara no anomena no sigui un canvi trencador: els registres desats encara poden anomenar-ne de fora d'ús.
items[].attemptsnumber- Quants intents de tramesa ha tingut el missatge, 0 abans del primer.
items[].lastErrorstring | null- L'error de tramesa més recent, escrit per a una persona. Null mentre no hagi fallat res.
items[].scheduledAtstring | null- Quan ha de sortir el missatge, com a instant ISO-8601. Null només en un enviament immediat sense finestra de cancel·lació: una finestra és un retard curt i res més, de manera que `cancellableForSeconds` també omple aquest camp, en una fila amb `status` `queued` i no pas `scheduled`.
items[].cancellableUntilstring | null- L'instant en què ha de sortir el missatge, amb el mateix valor que `scheduledAt` en qualsevol enviament que s'hagi ajornat i null en un que no. És una marca de temps per mostrar i no pas la comprovació que fa el servidor: `cancel` ramifica segons `status`, i només atura un missatge mentre encara és `queued` o `scheduled`.
items[].sentAtstring | null- Quan va sortir. Null fins que la tramesa s'ha completat, i per això el camp segons el qual ramificar és `status` i no aquest.
items[].tagsRecord<string, string>- Les etiquetes indicades en l'enviament, retornades i mai interpretades. Sempre un objecte (`{}` quan no se n'ha definit cap, mai null), i només retornades: aquest endpoint filtra per `status` i `from`, de manera que una etiqueta és una cosa per llegir d'un missatge i no pas una manera de trobar-ne un.
items[].sourceEmailSource- Quina superfície ha demanat l'enviament: `composer`, `api`, `mcp`, `ai` o `queue`. `api` és aquest client.
items[].createdAtstring- Quan es va escriure el registre d'enviament, que és abans de la tramesa. És el camp pel qual ordena la llista i el camp amb el qual compara un cursor.
items[].trackingEmailTrackingSummary- El resum d'interacció, present només en una fila el missatge de la qual s'ha seguit i absent en cas contrari. L'absència és la resposta a «s'ha fet seguiment d'això», mentre que `openCount: 0` es llegiria com a «ningú no l'ha obert».
items[].tracking.opensboolean- Si aquest missatge va sortir amb un píxel. El que se li va aplicar a aquest missatge, no pas el que diu ara la configuració del compte.
items[].tracking.clicksboolean- Si els enllaços d'aquest missatge es van reescriure. Fals quan el cos no tenia cap enllaç per reescriure, ja que llavors no es va canviar res.
items[].tracking.openedboolean- Si s'ha registrat alguna obertura comptabilitzada, derivat d'`openCount > 0`.
items[].tracking.clickedboolean- Si s'ha registrat algun clic comptabilitzat, derivat de `clickCount > 0`.
items[].tracking.openCountnumber- Obertures que es creu que ha provocat una persona, sumades sobre totes les còpies del missatge. Els escàners i els proxies de privadesa es registren però s'exclouen, i les descàrregues repetides dins de trenta segons es col·lapsen en una.
items[].tracking.clickCountnumber- Clics comptabilitzats, sumats sobre les còpies. Es desdupliquen per enllaç i no pas per missatge, perquè seguir dos enllaços amb segons de diferència són dos actes i no pas una repetició.
items[].tracking.firstOpenAtstring | null- L'obertura comptabilitzada més antiga entre les còpies, i null mentre no n'hi hagi cap. Les visites de màquines no la mouen mai.
items[].translationEmailTranslationResource- No hi és mai en una fila de llista: el registre de traducció viu dins de la sol·licitud desada, que una llista deliberadament no baixa. La seva absència aquí no diu res sobre si el missatge es va traduir. Pregunta-ho a `get`.