Python
Auflisten und abrufen
`emails.list`, `emails.list_all`, `emails.iterate`, `emails.get` und `emails.list_events`.
emails.list
from openemail import openemail first = openemail.emails.list(status=['queued', 'scheduled'], from_='[email protected]', limit=50) if first['nextCursor']: second = openemail.emails.list( status=['queued', 'scheduled'], from_='[email protected]', limit=50, cursor=first['nextCursor'], )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.list_all
import sys from openemail import openemail for email in openemail.emails.iterate(status='failed'): print(email['id'], email['lastError'], file=sys.stderr) failures = openemail.emails.list_all(status='failed', from_='[email protected]')Beide folgen nextCursor für Sie. iterate ist ein Generator, der eine Seite erst holt, wenn die Schleife sie erreicht, ein Abbruch stoppt daher die Anfragen, während list_all jede Seite durchläuft, bevor es eine einzige Liste zurückgibt; 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.list_events
from openemail import openemail email = openemail.emails.get('msg_…')print(email['status'], email['recipients']) events = openemail.emails.list_all_events('msg_…')for event in events: print(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 | Sequence[EmailStatus]- Ein Status oder mehrere (`queued`, `scheduled`, `sending`, `sent`, `partial`, `bounced`, `cancelled`, `failed`), passend auf einen beliebigen der angegebenen. Das SDK sendet eine Liste als einen einzelnen kommaseparierten Wert, weil der Server an Kommas trennt; ein Wert außerhalb dieser Menge ergibt ein 422, das den unbekannten nennt.
broadcast_idstr- Nur die Kopien eines Broadcasts, eine `brd_`-ID aus `broadcasts.send`. Jede Person, die ein Broadcast erreicht, bekommt eine eigene Nachricht, also listet dies auf, an wen er ging und was mit jeder Kopie geschah. `broadcasts.list_recipients` listet dieselben Personen mit ihren Öffnungen, Klicks und Abmeldungen auf.
from_str- 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. Der angehängte Unterstrich steht da, weil `from` ein Python-Schlüsselwort ist.
limitint- Zeilen auf dieser Seite, 1 bis 100, Standard 25. Ein Wert außerhalb dieses Bereichs wird als 422 abgelehnt und nicht begrenzt.
cursorstr- 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.
scheduled_fromdatetime | str- Nur Nachrichten, die für diesen Zeitpunkt oder später geplant sind: ein `datetime` oder ein ISO-8601-Zeitpunkt mit Zeitzone. Eine Nachricht ohne `scheduledAt` wird ausgelassen, mit `scheduled_to` und `status=['queued', 'scheduled']` listet dies also, was in einem Zeitfenster auf den Versand wartet.
scheduled_todatetime | str- Nur Nachrichten, die für diesen Zeitpunkt oder früher geplant sind. Ein `scheduled_from`, das später liegt, ergibt ein 422 `invalid_parameter` auf `scheduledTo`.
Antwort: Page[EmailResource]
itemslist[EmailResource]- 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`.
hasMorebool- 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.
nextCursorstr | None- Die id, die als `cursor` zurückzugeben ist, und null auf der letzten Seite. `iterate` und `list_all` stoppen, wenn dies null oder `hasMore` false ist, denn eine Seite, die mehr behauptet und dabei keinen cursor nennt, würde endlos kreisen.
items[].objectLiteral['email']- Immer `'email'` auf einer Zeile dieser Liste.
items[].idstr- 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. `bounced` heißt, dass sie nach dem Versand bei jedem Empfänger zurückgekommen ist, also hat sie niemand, und jeder Empfänger in `get` nennt den Grund.
items[].modeApiKeyMode- `live` oder `test`, übernommen vom Schlüssel, der sie gesendet hat. Ein Testversand wird hier erfasst und nie übertragen.
items[].fromstr- 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 dict, 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[].subjectstr | None- Der Betreff wie gespeichert. Null bei einer Nachricht, die ohne Betreff erfasst wurde.
items[].messageIdstr | None- 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[].threadIdstr | None- Der Thread, zu dem diese Nachricht gehört, sofern einer angegeben oder zugewiesen wurde. Andernfalls null.
items[].transportEmailTransport | str | None- 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[].attemptsint- Wie viele Versandversuche die Nachricht hatte, 0 vor dem ersten.
items[].lastErrorstr | None- Der jüngste Versandfehler, für Menschen formuliert. Null, solange nichts fehlgeschlagen ist.
items[].scheduledAtstr | None- 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[].cancellableUntilstr | None- 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[].sentAtstr | None- Wann sie hinausging. Null, bis der Versand abgeschlossen ist, weshalb `status` und nicht dieses Feld das Feld zum Verzweigen ist.
items[].tagsdict[str, str]- Die beim Senden angegebenen Labels, zurückgegeben und nie ausgewertet. Immer ein dict (`{}`, wenn keine gesetzt wurden, nie null) und nur zurückgegeben: Dieser Aufruf filtert nach `status`, `from_`, `broadcast_id`, `scheduled_from` und `scheduled_to`, ein Tag ist also etwas, das man an einer Nachricht abliest, kein Weg, eine zu finden.
items[].broadcastIdstr | None- Der `brd_`-Broadcast, von dem diese Nachricht eine Kopie ist, oder null für eine einzeln gesendete Nachricht.
items[].sourceEmailSource | str- Welche Oberfläche den Versand angefordert hat: `composer`, `api`, `mcp`, `ai`, `oauth` oder `form`. `api` ist dieser Client mit einem API-Schlüssel, und `oauth` ist dieser Client mit einem Zugriffstoken.
items[].createdAtstr- 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[].trackingNotRequired[EmailTrackingSummary]- 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.opensbool- Ob diese Nachricht mit einem Pixel hinausging. Was auf diese Nachricht angewendet wurde, nicht was die Kontoeinstellung jetzt sagt.
items[].tracking.clicksbool- Ob die Links dieser Nachricht umgeschrieben wurden. False, wenn der Body keine Links zum Umschreiben hatte, da dann nichts geändert wurde.
items[].tracking.openedbool- Ob irgendeine gezählte Öffnung erfasst wurde, abgeleitet aus `openCount > 0`.
items[].tracking.clickedbool- Ob irgendein gezählter Klick erfasst wurde, abgeleitet aus `clickCount > 0`.
items[].tracking.openCountint- Ö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.clickCountint- 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.firstOpenAtstr | None- Die früheste gezählte Öffnung über alle Kopien, und null, solange es keine gibt. Maschinelle Zugriffe verschieben sie nie.
items[].translationNotRequired[EmailTranslationResource]- 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`.