SDK

Auflisten und abrufen

`emails.list`, `emails.listAll`, `emails.iterate`, `emails.get` und `emails.listEvents`.

emails.list

list-emails.ts

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

Eine Seite ist { items, hasMore, nextCursor }. Übergeben Sie nextCursor mit denselben Filtern wieder als cursor, um die nächste Seite zu erhalten.

emails.iterate und emails.listAll

iterate-emails.ts

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 folgen nextCursor für Sie. iterate holt eine Seite erst, wenn die Schleife sie erreicht, ein Abbruch stoppt daher die Anfragen, während listAll jede Seite durchläuft, bevor es zu einem einzigen array auflöst, geben Sie ihm daher einen Filter, der endet. In beiden Fällen Keyset-Paginierung, eine mitten im Durchlauf eintreffende Nachricht kann daher nicht dazu führen, dass eine Zeile übersprungen wird, wie es bei einem offset der Fall wäre.

emails.get und emails.listEvents

get-email.ts

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 ist der einzige Aufruf, der recipients zurückgibt, eine Zeile pro Adresse. Eine Liste von fünfzig Nachrichten, die jeweils ihre Empfänger mitführen, ist eine Seite Bericht, um die niemand gebeten hat.

Parameter

statusEmailStatus | EmailStatus[]: Ein Status oder mehrere (`queued`, `scheduled`, `sending`, `sent`, `partial`, `cancelled`, `failed`), passend auf einen beliebigen der angegebenen. Das SDK sendet ein array als einen einzelnen kommaseparierten Wert, weil der Server an Kommas trennt; ein Wert außerhalb dieser Menge ergibt ein 422, das den unbekannten nennt.
fromstring: Exakte Übereinstimmung mit der Absenderadresse, wie sie erfasst wurde, also das blanke `addr@host` in Kleinbuchstaben. Die Zeile wird ohne jeden Anzeigenamen geschrieben, eine Angle-Addr wie `Acme <[email protected]>` passt daher auf nichts. Ihr Wert wird vor dem Vergleich in Kleinbuchstaben umgewandelt, und es gilt Gleichheit, kein Präfix- oder Domain-Vergleich.
limitnumber: Zeilen auf dieser Seite, 1 bis 100, Standard 25. Ein Wert außerhalb dieses Bereichs wird als 422 abgelehnt und nicht begrenzt.
cursorstring: Eine Nachrichten-id (`msg_…`), ab der paginiert wird. Keyset statt offset: Zurück kommen ausschließlich Zeilen, die älter sind als der `createdAt` dieser Nachricht, mitten in der Seite eintreffende Sendungen können daher keine Zeile an Ihnen vorbeischieben. Eine id, die keine Nachricht in diesem Workspace benennt, ergibt ein 400.

Antwort: Page<EmailResource>

itemsEmailResource[]: Eine Seite Nachrichten, neueste zuerst nach `createdAt`, aus dem `data`-Umschlag der API herausgehoben. Listenzeilen tragen nie die Aufschlüsselung `recipients` pro Adresse. Die gibt es bei `get`.
hasMoreboolean: Ob über diese Seite hinaus weitere Zeilen auf den Filter passen. Beantwortet durch das Holen einer Zeile mehr als `limit`, nicht durch eine zweite Zählabfrage.
nextCursorstring | null: Die id, die als `cursor` zurückzugeben ist, und null auf der letzten Seite. `iterate` und `listAll` stoppen, wenn dies null oder `hasMore` false ist, denn eine Seite, die mehr behauptet und dabei keinen cursor nennt, würde endlos kreisen.
items[].object'email': Immer `'email'` auf einer Zeile dieser Liste.
items[].idstring: Die eigene id dieser API, `msg_…`. Sie ist das, was jeder andere emails-Endpunkt entgegennimmt, und das, was ein cursor benennt.
items[].statusEmailStatus: Wo die Nachricht in ihrem Lebenszyklus steht. `partial` ist ein eigener Zustand und keine Spielart von failed: Einige Empfänger haben sie, und das lässt sich nicht rückgängig machen, ein erneuter Versuch ist daher falsch.
items[].modeApiKeyMode: `live` oder `test`, übernommen vom Schlüssel, der sie gesendet hat. Ein Testversand wird hier erfasst und nie übertragen.
items[].fromstring: Die Adresse, unter der der Versand autorisiert wurde, blank und in Kleinbuchstaben gespeichert, ein bei `from` angegebener Anzeigename geht also weiterhin auf die Leitung, wird hier aber nicht aufbewahrt. Ein einfacher String statt eines Objekts, weil dies die autorisierte Identität ist: Eine Adresse außerhalb des Sende-Scopes eines Schlüssels, weder auf einer Domain, die er hält, noch auf ihm benannt, wird mit einem 403 abgelehnt und nie stillschweigend gegen eine zulässige ausgetauscht.
items[].subjectstring | null: Der Betreff wie gespeichert. Null bei einer Nachricht, die ohne Betreff erfasst wurde.
items[].messageIdstring | null: Die Message-ID nach RFC 5322, nicht unsere id. Null, bis das MIME existiert, und vom Versanddienst auf dem Weg hinaus umgeschrieben, ein späterer Bounce oder DSN trägt daher eine andere id und wird stattdessen über `items[].id` zugeordnet.
items[].threadIdstring | null: Der Thread, zu dem diese Nachricht gehört, sofern einer angegeben oder zugewiesen wurde. Andernfalls null.
items[].transportEmailTransport | (string & {}) | null: Wie die Bytes hinausgingen. Null bis zum Versand, und offen typisiert, damit ein Transport, den dieses SDK noch nicht benennt, keine Breaking Change ist: Gespeicherte Datensätze können weiterhin solche nennen, die nicht mehr im Einsatz sind.
items[].attemptsnumber: Wie viele Versandversuche die Nachricht hatte, 0 vor dem ersten.
items[].lastErrorstring | null: Der jüngste Versandfehler, für Menschen formuliert. Null, solange nichts fehlgeschlagen ist.
items[].scheduledAtstring | null: Wann die Nachricht hinausgehen soll, als ISO-8601-Zeitpunkt. Null nur bei einem sofortigen Versand ohne Abbruchfenster: Ein Fenster ist nichts anderes als eine kurze Verzögerung, `cancellableForSeconds` füllt dies daher ebenfalls, auf einer Zeile, deren `status` `queued` und nicht `scheduled` ist.
items[].cancellableUntilstring | null: Der Zeitpunkt, zu dem die Nachricht hinausgehen soll, mit demselben Wert wie `scheduledAt` bei jedem aufgeschobenen Versand und null bei einem nicht aufgeschobenen. Ein Zeitstempel zum Anzeigen, nicht die Prüfung, die der Server vornimmt: `cancel` verzweigt über `status` und stoppt eine Nachricht nur, solange sie noch `queued` oder `scheduled` ist.
items[].sentAtstring | null: Wann sie hinausging. Null, bis der Versand abgeschlossen ist, weshalb `status` und nicht dieses Feld das Feld zum Verzweigen ist.
items[].tagsRecord<string, string>: Die beim Versand übergebenen Labels, zurückgegeben und nie interpretiert. Immer ein object (`{}`, wenn keine gesetzt wurden, nie null), und ausschließlich zurückgegeben: Dieser Endpunkt filtert über `status` und `from`, ein Tag ist daher etwas, das man an einer Nachricht abliest, und kein Weg, eine zu finden.
items[].sourceEmailSource: Welche Oberfläche den Versand angefordert hat: `composer`, `api`, `mcp`, `ai` oder `queue`. `api` ist dieser Client.
items[].createdAtstring: Wann der Versanddatensatz geschrieben wurde, was vor dem Versand liegt. Dies ist das Feld, nach dem die Liste sortiert, und das Feld, gegen das ein cursor vergleicht.
items[].trackingEmailTrackingSummary: Die Interaktionsübersicht, nur auf einer Zeile vorhanden, deren Nachricht getrackt wurde, sonst nicht vorhanden. Nicht vorhanden ist die Antwort auf "wurde das getrackt", während `openCount: 0` sich als "niemand hat es geöffnet" liest.
items[].tracking.opensboolean: Ob diese Nachricht mit einem Pixel hinausging. Was auf diese Nachricht angewendet wurde, nicht was die Kontoeinstellung jetzt sagt.
items[].tracking.clicksboolean: Ob die Links dieser Nachricht umgeschrieben wurden. False, wenn der Body keine Links zum Umschreiben hatte, da dann nichts geändert wurde.
items[].tracking.openedboolean: Ob irgendeine gezählte Öffnung erfasst wurde, abgeleitet aus `openCount > 0`.
items[].tracking.clickedboolean: Ob irgendein gezählter Klick erfasst wurde, abgeleitet aus `clickCount > 0`.
items[].tracking.openCountnumber: Öffnungen, die mutmaßlich von einem Menschen ausgelöst wurden, summiert über jede Kopie der Nachricht. Scanner und Datenschutz-Proxys werden erfasst, aber ausgeschlossen, und wiederholte Abrufe innerhalb von dreißig Sekunden werden zu einer zusammengefasst.
items[].tracking.clickCountnumber: Gezählte Klicks, summiert über die Kopien. Dedupliziert pro Link und nicht pro Nachricht, denn zwei Links im Abstand von Sekunden zu folgen sind zwei Handlungen und keine Wiederholung.
items[].tracking.firstOpenAtstring | null: Die früheste gezählte Öffnung über alle Kopien, und null, solange es keine gibt. Maschinelle Zugriffe verschieben sie nie.
items[].translationEmailTranslationResource: Auf einer Listenzeile nie vorhanden: Der Übersetzungsdatensatz liegt in der gespeicherten Anfrage, die eine Liste bewusst nicht holt. Sein Fehlen sagt hier nichts darüber aus, ob die Nachricht übersetzt wurde. Fragen Sie `get`.