SDK
Lijsten en ophalen
`emails.list`, `emails.listAll`, `emails.iterate`, `emails.get` en `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 }) : nullEen pagina is { items, hasMore, nextCursor }. Geef nextCursor terug als cursor, met dezelfde filters, voor de pagina erna.
emails.iterate en 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]' })Beide volgen nextCursor voor je. iterate haalt een pagina pas op wanneer de lus daar aankomt, dus uitbreken stopt de verzoeken, terwijl listAll elke pagina doorloopt voordat het tot één array oplost, dus geef die een filter dat eindigt. In beide gevallen keyset-paginering, dus een bericht dat halverwege de iteratie binnenkomt kan dit geen rij laten overslaan zoals een offset dat zou doen.
emails.get en 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 is de enige aanroep die recipients teruggeeft, één rij per adres. Een lijst van vijftig berichten die elk hun ontvangers meedragen is een pagina rapport waar niemand om vroeg.
Parameters
statusEmailStatus | EmailStatus[]- Eén status of meerdere (`queued`, `scheduled`, `sending`, `sent`, `partial`, `cancelled`, `failed`), waarbij op elk van de gegeven waarden gematcht wordt. De SDK stuurt een array als één door komma's gescheiden waarde omdat de server op komma's splitst; een waarde buiten die verzameling is een 422 die de onbekende noemt.
fromstring- Exacte match op het verzendende adres zoals het is vastgelegd, en dat is het kale `addr@host` in kleine letters. De rij wordt geschreven met een eventuele weergavenaam eraf gestript, dus een angle-addr zoals `Acme <[email protected]>` matcht niets. Je waarde wordt vóór de vergelijking naar kleine letters omgezet, en het is gelijkheid en geen prefix- of domeinmatch.
limitnumber- Rijen op deze pagina, 1 tot 100, standaard 25. Een waarde buiten dat bereik wordt geweigerd als 422 in plaats van afgekapt.
cursorstring- Een bericht-id (`msg_…`) om vanaf te pagineren. Keyset in plaats van offset: rijen komen strikt ouder terug dan de `createdAt` van dat bericht, dus verzendingen die halverwege een pagina binnenkomen kunnen geen rij voorbij je duwen. Een id die geen bericht in deze workspace noemt is een 400.
Antwoord: Page<EmailResource>
itemsEmailResource[]- Eén pagina berichten, nieuwste eerst op `createdAt`, uit de `data`-envelop van de API gelicht. Lijstrijen dragen nooit de uitsplitsing `recipients` per adres. Die zit op `get`.
hasMoreboolean- Of er voorbij deze pagina nog meer rijen op het filter passen. Beantwoord door één rij meer dan `limit` op te halen in plaats van door een tweede telquery.
nextCursorstring | null- De id die je als `cursor` terug moet geven, en null op de laatste pagina. `iterate` en `listAll` stoppen wanneer deze null is of `hasMore` onwaar, aangezien een pagina die meer beweert zonder een cursor te noemen eeuwig zou blijven rondgaan.
items[].object'email'- Altijd `'email'` op een rij van deze lijst.
items[].idstring- De eigen id van deze API, `msg_…`. Het is wat elk ander emails-endpoint accepteert, en wat een cursor noemt.
items[].statusEmailStatus- Waar het bericht in zijn leven staat. `partial` is een eigen status en geen variant van mislukt: sommige ontvangers hebben het en dat kan niet ongedaan gemaakt worden, dus opnieuw proberen is verkeerd.
items[].modeApiKeyMode- `live` of `test`, overgenomen van de sleutel die het verstuurde. Een testverzending wordt hier vastgelegd en nooit uitgezonden.
items[].fromstring- Het adres waaronder de verzending geautoriseerd werd, kaal en in kleine letters opgeslagen, zodat een weergavenaam die op `from` gegeven is wel over de lijn gaat maar hier niet bewaard wordt. Een gewone string in plaats van een object omdat dit de identiteit is die geautoriseerd werd: een adres buiten de verzendscope van een sleutel, niet op een domein dat hij bezit en er evenmin op genoemd, wordt geweigerd met een 403 en nooit stilletjes vervangen door een dat hij wel mag gebruiken.
items[].subjectstring | null- Het onderwerp zoals opgeslagen. Null op een bericht dat zonder onderwerp is vastgelegd.
items[].messageIdstring | null- De Message-ID uit RFC 5322, niet onze id. Null tot de MIME bestaat, en onderweg naar buiten herschreven door de verzenddienst, dus een latere bounce of DSN draagt een andere id en correleert in plaats daarvan op `items[].id`.
items[].threadIdstring | null- De thread waar dit bericht bij hoort, waar er een gegeven of toegewezen is. Anders null.
items[].transportEmailTransport | (string & {}) | null- Hoe de bytes vertrokken. Null tot de verzending, en open getypeerd zodat een transport dat deze SDK nog niet noemt geen breuk is: opgeslagen records kunnen nog transporten noemen die niet meer in gebruik zijn.
items[].attemptsnumber- Hoeveel verzendpogingen het bericht heeft gehad, 0 vóór de eerste.
items[].lastErrorstring | null- De meest recente verzendfout, geschreven voor een mens. Null zolang er niets is misgegaan.
items[].scheduledAtstring | null- Wanneer het bericht moet vertrekken, als een ISO-8601-tijdstip. Alleen null bij een directe verzending zonder annuleringsvenster: een venster is niet meer dan een korte vertraging, dus `cancellableForSeconds` vult dit ook in, op een rij waarvan de `status` `queued` is in plaats van `scheduled`.
items[].cancellableUntilstring | null- Het tijdstip waarop het bericht moet vertrekken, met dezelfde waarde als `scheduledAt` bij elke uitgestelde verzending en null bij een die dat niet was. Het is een tijdstempel om te tonen en niet de toets die de server uitvoert: `cancel` vertakt op `status` en stopt een bericht alleen zolang het nog `queued` of `scheduled` is.
items[].sentAtstring | null- Wanneer het wegging. Null tot de verzending voltooid is, en daarom is `status` en niet dit het veld om op te vertakken.
items[].tagsRecord<string, string>- De labels die bij de verzending zijn meegegeven, teruggegeven en nooit geïnterpreteerd. Altijd een object (`{}` waar er geen zijn gezet, nooit null), en alleen teruggegeven: dit endpoint filtert op `status` en `from`, dus een tag is iets om van een bericht af te lezen en geen manier om er een te vinden.
items[].sourceEmailSource- Welke oppervlakte om de verzending vroeg: `composer`, `api`, `mcp`, `ai` of `queue`. `api` is deze client.
items[].createdAtstring- Wanneer het verzendrecord is geschreven, en dat is vóór de verzending. Dit is het veld waarop de lijst sorteert en het veld waartegen een cursor vergelijkt.
items[].trackingEmailTrackingSummary- De samenvatting van de betrokkenheid, alleen aanwezig op een rij waarvan het bericht getrackt werd en anders afwezig. Afwezig is het antwoord op "is dit getrackt", waar `openCount: 0` zou lezen als "niemand heeft het geopend".
items[].tracking.opensboolean- Of dit bericht met een pixel vertrok. Wat op dit bericht is toegepast, niet wat de accountinstelling nu zegt.
items[].tracking.clicksboolean- Of de links van dit bericht zijn herschreven. Onwaar wanneer de body geen links had om te herschrijven, aangezien er dan niets is gewijzigd.
items[].tracking.openedboolean- Of er een getelde opening is vastgelegd, afgeleid uit `openCount > 0`.
items[].tracking.clickedboolean- Of er een getelde klik is vastgelegd, afgeleid uit `clickCount > 0`.
items[].tracking.openCountnumber- Openingen waarvan wordt aangenomen dat een persoon ze veroorzaakte, opgeteld over elke kopie van het bericht. Scanners en privacyproxy's worden vastgelegd maar uitgesloten, en herhaalde ophaalacties binnen dertig seconden vallen samen tot één.
items[].tracking.clickCountnumber- Getelde kliks, opgeteld over de kopieën. Ontdubbeld per link in plaats van per bericht, want twee links volgen met seconden ertussen zijn twee handelingen en geen herhaling.
items[].tracking.firstOpenAtstring | null- De vroegste getelde opening over de kopieën, en null zolang die er niet is. Machinehits verschuiven hem nooit.
items[].translationEmailTranslationResource- Nooit aanwezig op een lijstrij: het vertaalrecord zit in het opgeslagen verzoek, dat een lijst bewust niet ophaalt. De afwezigheid hier zegt niets over of het bericht vertaald werd. Vraag het aan `get`.