Ruby

Auflisten und abrufen

`emails.list`, `emails.list_all`, `emails.iterate`, `emails.get` und `emails.list_events`.

emails.list

list_emails.rb

filters = {status: ["queued", "scheduled"], from: "[email protected]"} first = client.emails.list(**filters, limit: 50)second = client.emails.list(**filters, limit: 50, cursor: first.next_cursor) if first.next_cursor p first.items.size, second&.items&.size

Eine Seite ist eine OpenEmail::Page mit items, has_more? und next_cursor. Übergeben Sie next_cursor mit denselben Filtern wieder als cursor:, um die nächste Seite zu erhalten.

emails.iterate und emails.list_all

iterate_emails.rb

client.emails.iterate(status: "failed") do |email|  warn "#{email[:id]} #{email[:lastError]}"end failures = client.emails.list_all(status: "failed", from: "[email protected]")puts failures.size

Beide folgen next_cursor für Sie. iterate holt eine Seite erst, wenn der Durchlauf sie erreicht. break im Block oder first oder find auf dem Enumerator, den es ohne Block zurückgibt, stoppt daher die Anfragen, während list_all jede Seite durchläuft, bevor es ein einziges Array 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

get_email.rb

email = client.emails.get("msg_3f9a1c07d2b84e6a9c5b1f20")puts email[:status]p email[:recipients] events = client.emails.list_all_events("msg_3f9a1c07d2b84e6a9c5b1f20")events.each { |event| puts "#{event[:type]} #{event[:createdAt]}" }

get ist der einzige Aufruf, der recipients zurückgibt, einen Hash pro Adresse mit eigenem status, error und deliveredAt. Eine Liste von fünfzig Nachrichten, die jeweils ihre Empfänger mitführen, ist eine Seite Bericht, um die niemand gebeten hat.

list_events liest die Ereignisspur eines Versands, die ältesten zuerst: email.accepted, email.queued, email.sent, email.delivered, email.bounced, email.opened und die übrigen, jeweils mit einem data-Hash, dessen Form von seinem type abhängt. list_all_events und iterate_events durchlaufen die ganze Spur für Sie. Webhooks liefern eine Teilmenge derselben Ereignisse, während sie geschehen. Hier sehen Sie also nach, wenn ein Webhook verpasst wurde.

Parameter

statusString or Array<String>: Ein Status oder mehrere (`queued`, `scheduled`, `sending`, `sent`, `partial`, `bounced`, `cancelled`, `failed`), passend auf einen beliebigen der angegebenen. `bounced` bedeutet, dass die Nachricht bei jedem Empfänger als Bounce zurückkam, während eine Nachricht, die bei einigen als Bounce zurückkam und die übrigen erreichte, `partial` zeigt. Das Gem sendet ein Array als einen einzelnen kommaseparierten Wert, weil der Server an Kommas trennt, und ein Wert außerhalb der Menge ergibt einen 422, der den unbekannten nennt.
broadcast_idString: 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.
fromString: Exakte Übereinstimmung mit der Absenderadresse, wie sie erfasst wurde, also das bloße `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.
scheduled_fromTime, DateTime or String: Nur Nachrichten, die für diesen Zeitpunkt oder später geplant sind. Mit `scheduled_to:` und `status: ["scheduled", "queued"]` listet es auf, was in einem Zeitfenster auf den Versand wartet, so wie es der Kalender der App tut. Eine Nachricht ohne `scheduledAt` wird ausgelassen. Übergeben Sie ein Time, ein DateTime oder einen Zeitpunkt nach ISO 8601 mit Offset: Ein Ruby-Date wird als bloßes Datum gesendet, und das lehnen diese beiden Filter ab.
scheduled_toTime, DateTime or String: Nur Nachrichten, die für diesen Zeitpunkt oder früher geplant sind. Ein `scheduled_from:` nach `scheduled_to:` ergibt einen 422 `invalid_parameter`.
limitInteger: Zeilen auf dieser Seite, 1 bis 100, Standard 25. Ein Wert außerhalb dieses Bereichs wird mit einem 422 abgelehnt und nicht begrenzt. Bei `list_all` und `iterate` ist es die Größe jeder Seite, die sie holen.
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 Versände können daher keine Zeile an Ihnen vorbeischieben. Eine id, die keine Nachricht in diesem Workspace benennt, ergibt einen 400 `invalid_cursor`.
api_keyString: Listet mit diesem Schlüssel statt mit dem des Clients auf.

Ein auf bestimmte Adressen eingeschränkter Schlüssel liest nur die Nachrichten, die von Adressen gesendet wurden, die er abdeckt, und die Seite wird erst nach diesem Filter zugeschnitten. Jede Seite außer der letzten enthält also weiterhin limit Zeilen. Ein from:, das der Schlüssel nicht abdeckt, ergibt eine leere letzte Seite statt eines 403.

Antwort: OpenEmail::Page

itemsArray<Hash>: 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`.
has_more?Boolean: 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.
next_cursorString or nil: Die id, die als `cursor:` zurückzugeben ist, und nil auf der letzten Seite. `iterate` und `list_all` stoppen, wenn dies nil oder `has_more?` false ist, denn eine Seite, die mehr behauptet und dabei keinen Cursor nennt, würde endlos kreisen.

Jeder Eintrag

objectString: Immer `email` auf einer Zeile dieser Liste.
idString: Die eigene id dieser API, `msg_…`. Sie ist das, was jeder andere emails-Aufruf entgegennimmt, und das, was ein Cursor benennt.
statusString: 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.
modeString: `live` oder `test`, übernommen vom Schlüssel, der sie gesendet hat. Ein Testversand wird hier erfasst und nie übertragen.
fromString: Die Adresse, unter der der Versand autorisiert wurde, bloß 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 Hashes, 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.
subjectString or nil: Der Betreff wie gespeichert. nil bei einer Nachricht, die ohne Betreff erfasst wurde.
messageIdString or nil: Die Message-ID nach RFC 5322, nicht unsere id. nil, 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 `id` zugeordnet.
threadIdString or nil: Der Thread, zu dem diese Nachricht gehört, sofern einer angegeben oder zugewiesen wurde. Andernfalls nil.
transportString or nil: Wie die Bytes hinausgingen. nil bis zum Versand. Gespeicherte Datensätze können noch Transporte nennen, die nicht mehr verwendet werden. Behandeln Sie einen unbekannten Wert daher als Information und nicht als Fehler.
attemptsInteger: Wie viele Versandversuche die Nachricht hatte, 0 vor dem ersten.
lastErrorString or nil: Der jüngste Versandfehler, für Menschen formuliert. nil, solange nichts fehlgeschlagen ist.
scheduledAtString or nil: Wann die Nachricht hinausgehen soll, als Zeitpunkt nach ISO 8601. nil 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.
cancellableUntilString or nil: Der Zeitpunkt, zu dem die Nachricht hinausgehen soll, mit demselben Wert wie `scheduledAt` bei jedem aufgeschobenen Versand und nil 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.
sentAtString or nil: Wann sie hinausging. nil, bis der Versand abgeschlossen ist, weshalb `status` und nicht dieses Feld das Feld zum Verzweigen ist.
tagsHash: Die beim Senden angegebenen Labels, zurückgegeben und nie ausgewertet. Immer ein Hash, leer, wenn keine gesetzt wurden, nie nil, und nur zurückgegeben: Diese Liste filtert nach `status`, `from`, `broadcast_id` und dem Planungsfenster, ein Tag ist also etwas, das man an einer Nachricht abliest, kein Weg, eine zu finden.
broadcastIdString or nil: Der `brd_`-Broadcast, von dem diese Nachricht eine Kopie ist, oder nil für eine einzeln gesendete Nachricht.
sourceString: Welche Oberfläche den Versand angefordert hat: `composer`, `api`, `mcp`, `ai` oder `queue`. `api` ist dieser Client.
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.
trackingHash: Die Interaktionsübersicht, nur auf einer Zeile vorhanden, deren Nachricht getrackt wurde, sonst nicht vorhanden. Das Fehlen ist die Antwort auf „wurde das getrackt“, während ein `openCount` von 0 sich als „niemand hat es geöffnet“ läse.
translationHash: 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`.

Das Tracking eines Eintrags

opensBoolean: Ob diese Nachricht mit einem Pixel hinausging. Was auf diese Nachricht angewendet wurde, nicht was die Kontoeinstellung jetzt sagt.
clicksBoolean: Ob die Links dieser Nachricht umgeschrieben wurden. False, wenn der Body keine Links zum Umschreiben hatte, da dann nichts geändert wurde.
openedBoolean: Ob irgendeine gezählte Öffnung erfasst wurde, abgeleitet aus einem `openCount` über 0.
clickedBoolean: Ob irgendein gezählter Klick erfasst wurde, abgeleitet aus einem `clickCount` über 0.
openCountInteger: Ö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.
clickCountInteger: 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.
firstOpenAtString or nil: Die früheste gezählte Öffnung über alle Kopien, und nil, solange es keine gibt. Maschinelle Zugriffe verschieben sie nie.