SDK
Výpis a načtení
`emails.list`, `emails.listAll`, `emails.iterate`, `emails.get` a `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 }) : nullStránka je { items, hasMore, nextCursor }. Pro následující stránku pošlete nextCursor zpět jako cursor, se stejnými filtry.
emails.iterate a 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]' })Obě sledují nextCursor za vás. iterate načte stránku teprve tehdy, když k ní cyklus dojde, takže vyskočení z cyklu požadavky zastaví, zatímco listAll projde všechny stránky, než se vyřeší do jediného pole – dejte mu tedy filtr, který někde skončí. Tak či tak jde o stránkování podle klíče, takže zpráva, která dorazí uprostřed iterace, nemůže způsobit přeskočení řádku, jak by se stalo při offsetu.
emails.get a 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 je jediné volání, které vrací recipients, jeden řádek na adresu. Seznam padesáti zpráv, z nichž každá nese své příjemce, je stránka hlášení, o kterou nikdo nežádal.
Parametry
statusEmailStatus | EmailStatus[]- Jeden stav nebo několik (`queued`, `scheduled`, `sending`, `sent`, `partial`, `cancelled`, `failed`); odpovídá kterémukoli ze zadaných. SDK posílá pole jako jedinou hodnotu oddělenou čárkami, protože server dělí podle čárek; hodnota mimo tuto množinu je 422 s uvedením té neznámé.
fromstring- Přesná shoda s odesílací adresou tak, jak byla zaznamenána, tedy holé `addr@host` převedené na malá písmena. Řádek se zapisuje bez zobrazovaného jména, takže tvar v lomených závorkách jako `Acme <[email protected]>` neodpovídá ničemu. Vaše hodnota se před porovnáním převede na malá písmena a jde o rovnost, ne o shodu prefixu nebo domény.
limitnumber- Počet řádků na této stránce, 1 až 100, výchozí 25. Hodnota mimo tento rozsah je odmítnuta jako 422, ne oříznuta na mez.
cursorstring- Id zprávy (`msg_…`), od které se má stránkovat. Podle klíče, ne podle offsetu: vracejí se řádky výhradně starší než `createdAt` té zprávy, takže odeslání, která dorazí uprostřed stránkování, vám žádný řádek nemohou protlačit kolem. Id, které v tomto pracovním prostoru nepojmenovává žádnou zprávu, je 400.
Odpověď: Page<EmailResource>
itemsEmailResource[]- Jedna stránka zpráv, od nejnovějších podle `createdAt`, vytažená z obálky `data` v API. Řádky seznamu nikdy nenesou rozpis `recipients` po adresách. Ten je na `get`.
hasMoreboolean- Zda filtru odpovídají další řádky i za touto stránkou. Zjišťuje se načtením o jeden řádek víc, než je `limit`, ne druhým dotazem na počet.
nextCursorstring | null- Id, které se má vrátit jako `cursor`; na poslední stránce null. `iterate` a `listAll` se zastaví, když je null nebo je `hasMore` false, protože stránka, která tvrdí, že je toho víc, a přitom žádný kurzor neuvádí, by se zacyklila donekonečna.
items[].object'email'- Na řádku tohoto seznamu vždy `'email'`.
items[].idstring- Vlastní id tohoto API, `msg_…`. Je to to, co přijímá každý další endpoint emails, a to, co pojmenovává kurzor.
items[].statusEmailStatus- Kde se zpráva nachází ve svém životě. `partial` je samostatný stav, ne odrůda selhání: někteří příjemci ji mají a odeslání jim nelze vzít zpět, takže opakovat odeslání je chyba.
items[].modeApiKeyMode- `live` nebo `test`, podle klíče, který zprávu odeslal. Testovací odeslání se sem zaznamená a nikdy se nepřenáší.
items[].fromstring- Adresa, pod kterou bylo odeslání autorizováno, uložená holá a malými písmeny, takže zobrazované jméno zadané v `from` sice po drátě odejde, ale zde se neuchovává. Prostý řetězec, ne objekt, protože jde o identitu, která byla autorizována: adresa mimo rozsah odesílání daného klíče, tedy ani na doméně, kterou klíč drží, ani na něm výslovně uvedená, je odmítnuta s 403, nikdy tiše vyměněna za takovou, kterou drží.
items[].subjectstring | null- Předmět tak, jak byl uložen. Null u zprávy zaznamenané bez předmětu.
items[].messageIdstring | null- Message-ID podle RFC 5322, ne naše id. Null, dokud MIME neexistuje, a odesílací služba jej cestou ven přepisuje, takže pozdější bounce nebo DSN nese jiné id a páruje se místo toho přes `items[].id`.
items[].threadIdstring | null- Vlákno, do kterého tato zpráva patří, pokud bylo zadáno nebo přiřazeno. Jinak null.
items[].transportEmailTransport | (string & {}) | null- Jak bajty odešly. Null až do odeslání; typ je otevřený, aby transport, který toto SDK ještě nepojmenovává, nebyl rozbíjející změnou: uložené záznamy mohou stále uvádět i ty, které se už nepoužívají.
items[].attemptsnumber- Kolik pokusů o odeslání zpráva měla, 0 před prvním.
items[].lastErrorstring | null- Poslední chyba při odesílání, psaná pro člověka. Null, dokud nic neselhalo.
items[].scheduledAtstring | null- Kdy má zpráva odejít, jako okamžik podle ISO-8601. Null jen u okamžitého odeslání bez okna pro zrušení: okno není nic jiného než krátké zpoždění, takže `cancellableForSeconds` tuto hodnotu vyplní také, a to na řádku, jehož `status` je `queued`, ne `scheduled`.
items[].cancellableUntilstring | null- Okamžik, kdy má zpráva odejít; u každého odloženého odeslání nese stejnou hodnotu jako `scheduledAt` a u neodloženého je null. Je to časový údaj k zobrazení, ne test, který dělá server: `cancel` se větví podle `status` a zprávu zastaví jen tehdy, dokud je ještě `queued` nebo `scheduled`.
items[].sentAtstring | null- Kdy odešla. Null, dokud se odeslání nedokončí, proto je polem k větvení `status`, a ne tohle.
items[].tagsRecord<string, string>- Štítky zadané při odeslání, vrácené zpět a nikdy nijak neinterpretované. Vždy objekt (`{}`, když žádné nebyly nastaveny, nikdy null), a pouze vracené: tento endpoint filtruje podle `status` a `from`, takže štítek je něco, co si přečtete ze zprávy, ne způsob, jak ji najít.
items[].sourceEmailSource- Které rozhraní o odeslání požádalo: `composer`, `api`, `mcp`, `ai` nebo `queue`. `api` je tento klient.
items[].createdAtstring- Kdy byl zapsán záznam o odeslání, což je dřív než samotné odeslání. Podle tohoto pole se seznam řadí a proti němu porovnává kurzor.
items[].trackingEmailTrackingSummary- Souhrn interakcí, přítomný jen na řádku, jehož zpráva byla sledována, jinak chybí. Nepřítomnost je odpovědí na otázku „bylo tohle sledováno“, kde by `openCount: 0` znamenalo „nikdo to neotevřel“.
items[].tracking.opensboolean- Zda tato zpráva odešla s pixelem. Jde o to, co bylo na tuto zprávu uplatněno, ne o to, co říká nastavení účtu teď.
items[].tracking.clicksboolean- Zda byly odkazy v této zprávě přepsány. False, když tělo žádné odkazy k přepsání nemělo, protože se pak nic nezměnilo.
items[].tracking.openedboolean- Zda bylo zaznamenáno nějaké započítané otevření; odvozeno z `openCount > 0`.
items[].tracking.clickedboolean- Zda bylo zaznamenáno nějaké započítané kliknutí; odvozeno z `clickCount > 0`.
items[].tracking.openCountnumber- Otevření, o kterých se předpokládá, že je způsobil člověk, sečtená přes všechny kopie zprávy. Skenery a soukromí chránící proxy se zaznamenávají, ale nezapočítávají, a opakovaná načtení do třiceti sekund se slučují do jednoho.
items[].tracking.clickCountnumber- Započítaná kliknutí, sečtená přes kopie. Deduplikují se po jednotlivých odkazech, ne po zprávě, protože otevřít dva odkazy pár sekund po sobě jsou dva činy, ne opakování.
items[].tracking.firstOpenAtstring | null- Nejstarší započítané otevření napříč kopiemi; dokud žádné není, null. Strojové přístupy jím nikdy nepohnou.
items[].translationEmailTranslationResource- Na řádku seznamu nikdy není: záznam o překladu je uložen v uloženém požadavku, který seznam záměrně nenačítá. Jeho nepřítomnost zde neříká nic o tom, zda byla zpráva přeložena. Zeptejte se přes `get`.