SDK

Lista i pobranie

`emails.list`, `emails.listAll`, `emails.iterate`, `emails.get` i `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

Strona to { items, hasMore, nextCursor }. Odeślij nextCursor jako cursor, z tymi samymi filtrami, żeby dostać następną.

emails.iterate i 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]' })

Obie podążają za nextCursor za Ciebie. iterate pobiera stronę dopiero, gdy pętla do niej dojdzie, więc wyjście z pętli zatrzymuje żądania, a listAll przechodzi każdą stronę, zanim rozwiąże się jedną tablicą, więc daj jej filtr, który się kończy. W obu przypadkach stronicowanie kluczowe (keyset), więc wiadomość przychodząca w trakcie iteracji nie sprawi, że pominiesz wiersz, jak stałoby się przy offsetach.

emails.get i 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 to jedyne wywołanie zwracające recipients, po jednym wierszu na adres. Lista pięćdziesięciu wiadomości, z których każda niesie swoich odbiorców, to strona raportu, o który nikt nie prosił.

Parametry

statusEmailStatus | EmailStatus[]: Jeden status albo kilka (`queued`, `scheduled`, `sending`, `sent`, `partial`, `cancelled`, `failed`), dopasowując dowolny z podanych. SDK wysyła tablicę jako jedną wartość rozdzieloną przecinkami, bo serwer dzieli po przecinkach; wartość spoza tego zbioru daje 422 nazywające nieznaną.
fromstring: Dokładne dopasowanie do adresu nadawczego w postaci, w jakiej go zapisano, czyli samego `addr@host` małymi literami. Wiersz jest zapisywany z usuniętą nazwą wyświetlaną, więc adres w postaci `Acme <[email protected]>` nie dopasuje niczego. Twoja wartość jest przed porównaniem zamieniana na małe litery, a porównanie to równość, a nie prefiks czy dopasowanie domeny.
limitnumber: Wierszy na tej stronie, od 1 do 100, domyślnie 25. Wartość spoza tego zakresu jest odrzucana jako 422, a nie przycinana.
cursorstring: Identyfikator wiadomości (`msg_…`), od której stronicować. Kluczowe (keyset), a nie offsetowe: wiersze wracają ściśle starsze niż `createdAt` tamtej wiadomości, więc wysyłki pojawiające się w trakcie strony nie mogą przepchnąć wiersza obok Ciebie. Identyfikator nienazywający żadnej wiadomości w tej przestrzeni roboczej daje 400.

Odpowiedź: Page<EmailResource>

itemsEmailResource[]: Jedna strona wiadomości, od najnowszych po `createdAt`, wyjęta z koperty `data` API. Wiersze listy nigdy nie niosą rozbicia `recipients` na adresy. To jest w `get`.
hasMoreboolean: Czy poza tą stroną są jeszcze wiersze pasujące do filtra. Odpowiadane przez pobranie jednego wiersza ponad `limit`, a nie drugim zapytaniem zliczającym.
nextCursorstring | null: Identyfikator do odesłania jako `cursor`, null na ostatniej stronie. `iterate` i `listAll` zatrzymują się, gdy jest null albo gdy `hasMore` jest false, bo strona twierdząca, że jest więcej, ale nienazywająca kursora, zapętliłaby się na zawsze.
items[].object'email': Zawsze `'email'` na wierszu tej listy.
items[].idstring: Własny identyfikator tego API, `msg_…`. To on jest przyjmowany przez każdy inny endpoint emails i to jego nazywa kursor.
items[].statusEmailStatus: Gdzie wiadomość jest w swoim życiu. `partial` to osobny stan, a nie odmiana porażki: część odbiorców ją ma i nie da się tego cofnąć, więc ponawianie jest błędem.
items[].modeApiKeyMode: `live` albo `test`, wzięte z klucza, który ją wysłał. Wysyłka testowa jest tu zapisywana i nigdy nie jest transmitowana.
items[].fromstring: Adres, pod którym wysyłkę autoryzowano, zapisany samodzielnie i małymi literami, więc nazwa wyświetlana podana w `from` wychodzi wprawdzie na łącze, ale nie jest tu przechowywana. Zwykły ciąg, a nie obiekt, bo to jest tożsamość, którą autoryzowano: adres spoza zakresu wysyłki klucza, ani w domenie, którą klucz obejmuje, ani na nim nazwany, jest odrzucany z 403, a nigdy po cichu podmieniany na taki, który wolno.
items[].subjectstring | null: Temat w postaci zapisanej. Null na wiadomości zapisanej bez niego.
items[].messageIdstring | null: Message-ID z RFC 5322, a nie nasz identyfikator. Null, dopóki nie powstanie MIME, i przepisywany przez usługę wysyłkową na wyjściu, więc późniejszy bounce albo DSN niesie inny identyfikator i koreluje po `items[].id`.
items[].threadIdstring | null: Wątek, do którego należy ta wiadomość, o ile jakiś podano lub przypisano. W przeciwnym razie null.
items[].transportEmailTransport | (string & {}) | null: Jak wyszły bajty. Null do czasu wysłania i typowane otwarcie, żeby transport, którego ten SDK jeszcze nie nazywa, nie był zmianą łamiącą: zapisane rekordy wciąż mogą nazywać takie, które nie są już w użyciu.
items[].attemptsnumber: Ile prób wysłania miała wiadomość, 0 przed pierwszą.
items[].lastErrorstring | null: Ostatni błąd wysyłania, napisany dla człowieka. Null, dopóki nic się nie wywróciło.
items[].scheduledAtstring | null: Kiedy wiadomość ma wyjść, jako instant ISO-8601. Null wyłącznie przy wysyłce natychmiastowej bez okna anulowania: okno to tylko krótkie opóźnienie i nic więcej, więc `cancellableForSeconds` też to pole wypełnia, na wierszu, którego `status` to `queued`, a nie `scheduled`.
items[].cancellableUntilstring | null: Instant, w którym wiadomość ma wyjść, niosący tę samą wartość co `scheduledAt` na każdej wysyłce odroczonej i null na nieodroczonej. To znacznik czasu do pokazania, a nie test, który robi serwer: `cancel` rozgałęzia się na `status` i zatrzymuje wiadomość tylko, dopóki jest `queued` albo `scheduled`.
items[].sentAtstring | null: Kiedy poszła. Null, dopóki wysyłanie się nie zakończy, i dlatego to `status`, a nie to pole, jest tym, na czym się rozgałęziać.
items[].tagsRecord<string, string>: Etykiety podane przy wysyłce, odsyłane z powrotem i nigdy nieinterpretowane. Zawsze obiekt (`{}`, gdy nie ustawiono żadnych, nigdy null) i tylko odsyłane: ten endpoint filtruje po `status` i `from`, więc etykieta to coś, co odczytujesz z wiadomości, a nie sposób na jej znalezienie.
items[].sourceEmailSource: Która powierzchnia poprosiła o wysyłkę: `composer`, `api`, `mcp`, `ai` albo `queue`. `api` to ten klient.
items[].createdAtstring: Kiedy zapisano rekord wysyłki, czyli przed wysłaniem. To po tym polu lista sortuje i z tym polem porównuje kursor.
items[].trackingEmailTrackingSummary: Podsumowanie zaangażowania, obecne tylko na wierszu, którego wiadomość była śledzona, i nieobecne w przeciwnym razie. Nieobecność jest odpowiedzią na pytanie „czy to było śledzone”, gdzie `openCount: 0` czytałoby się jako „nikt tego nie otworzył”.
items[].tracking.opensboolean: Czy ta wiadomość wyszła z pikselem. To, co zastosowano do tej wiadomości, a nie to, co mówi dziś ustawienie konta.
items[].tracking.clicksboolean: Czy linki w tej wiadomości zostały przepisane. False, gdy treść nie miała linków do przepisania, bo wtedy nic nie zmieniono.
items[].tracking.openedboolean: Czy zarejestrowano jakiekolwiek liczone otwarcie, wyprowadzane z `openCount > 0`.
items[].tracking.clickedboolean: Czy zarejestrowano jakiekolwiek liczone kliknięcie, wyprowadzane z `clickCount > 0`.
items[].tracking.openCountnumber: Otwarcia uznane za spowodowane przez człowieka, zsumowane po każdej kopii wiadomości. Skanery i proxy prywatności są rejestrowane, ale wyłączone z liczenia, a powtórne pobrania w ciągu trzydziestu sekund zwijają się w jedno.
items[].tracking.clickCountnumber: Liczone kliknięcia, zsumowane po kopiach. Deduplikowane per link, a nie per wiadomość, bo otwarcie dwóch linków w odstępie sekund to dwa akty, a nie powtórzenie.
items[].tracking.firstOpenAtstring | null: Najwcześniejsze liczone otwarcie spośród kopii, null, dopóki go nie ma. Trafienia maszynowe nigdy nim nie ruszają.
items[].translationEmailTranslationResource: Nigdy nieobecne na wierszu listy: rekord tłumaczenia żyje w zapisanym żądaniu, którego lista celowo nie pobiera. Jego brak tutaj nie mówi nic o tym, czy wiadomość przetłumaczono. Zapytaj `get`.