Python
Listeleme ve getirme
`emails.list`, `emails.list_all`, `emails.iterate`, `emails.get` ve `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'], )Bir sayfa {'items': [...], 'hasMore': ..., 'nextCursor': ...} biçimindedir. Sonraki sayfa için nextCursor değerini aynı filtrelerle cursor olarak geri geçirin.
emails.iterate ve 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]')İkisi de nextCursor değerini sizin için izler. iterate, bir sayfayı yalnızca döngü oraya ulaştığında getiren bir üreteçtir, dolayısıyla döngüden çıkmak istekleri durdurur; list_all ise tek bir liste döndürmeden önce her sayfayı dolaşır, bu yüzden ona sonu olan bir filtre verin. Her iki durumda da keyset sayfalama kullanılır; böylece gezinme sırasında gelen bir mesaj, offset'in yapacağı gibi bir satırı atlamanıza yol açamaz.
emails.get ve 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'])recipients alanını döndüren tek çağrı get'tir; adres başına bir satır. Her biri alıcılarını taşıyan elli mesajlık bir liste, kimsenin istemediği bir rapor sayfası olurdu.
Parametreler
statusEmailStatus | Sequence[EmailStatus]- Bir veya birkaç durum (`queued`, `scheduled`, `sending`, `sent`, `partial`, `bounced`, `cancelled`, `failed`); verilenlerden herhangi biriyle eşleşir. SDK bir listeyi virgülle ayrılmış tek bir değer olarak gönderir, çünkü sunucu virgüllerden böler; bu kümenin dışındaki bir değer, bilinmeyeni adıyla belirten bir 422 verir.
broadcast_idstr- Yalnızca bir toplu gönderimin kopyaları; `broadcasts.send`'den gelen bir `brd_` kimliği. Bir toplu gönderimin ulaştığı her kişi kendi iletisini alır, bu yüzden bu, kime gittiğini ve her kopyaya ne olduğunu listeler. `broadcasts.list_recipients` aynı kişileri açmaları, tıklamaları ve abonelikten çıkmalarıyla listeler.
from_str- Kaydedildiği hâliyle gönderen adresle birebir eşleşme; yani küçük harfe çevrilmiş çıplak `addr@host`. Satır, görünen ad temizlenerek yazılır; dolayısıyla `Acme <[email protected]>` gibi açılı ayraçlı bir adres hiçbir şeyle eşleşmez. Verdiğiniz değer karşılaştırmadan önce küçük harfe çevrilir ve bu bir önek veya alan adı eşleşmesi değil, eşitlik karşılaştırmasıdır. Sondaki alt çizgi, `from` bir Python anahtar sözcüğü olduğu için oradadır.
limitint- Bu sayfadaki satır sayısı, 1 ila 100, varsayılan 25. Bu aralığın dışındaki bir değer sınıra çekilmek yerine 422 ile reddedilir.
cursorstr- Sayfalamanın başlayacağı mesaj id'si (`msg_…`). Offset değil keyset: satırlar o mesajın `createdAt` değerinden kesinlikle daha eski olarak gelir; böylece sayfa dolaşılırken gelen gönderimler bir satırı sizden öteye itemez. Bu çalışma alanında hiçbir mesajı göstermeyen bir id 400 verir.
scheduled_fromdatetime | str- Yalnızca bu ana veya sonrasına zamanlanmış mesajlar: bir `datetime` ya da saat dilimi içeren bir ISO-8601 anı. `scheduledAt` değeri olmayan bir mesaj dışarıda kalır; bu yüzden `scheduled_to` ve `status=['queued', 'scheduled']` ile birlikte bu, belirli bir zaman aralığında çıkmayı bekleyenleri listeler.
scheduled_todatetime | str- Yalnızca bu ana veya öncesine zamanlanmış mesajlar. Bundan daha geç bir `scheduled_from`, `scheduledTo` üzerinde 422 `invalid_parameter` verir.
Yanıt: Page[EmailResource]
itemslist[EmailResource]- `createdAt` değerine göre en yeniden eskiye sıralanmış tek sayfalık mesaj; API'nin `data` zarfından çıkarılmıştır. Liste satırları adres başına `recipients` dökümünü asla taşımaz. O döküm `get` üzerindedir.
hasMorebool- Filtreyle eşleşen, bu sayfanın ötesinde başka satır olup olmadığı. İkinci bir sayım sorgusuyla değil, `limit` değerinden bir satır fazla getirilerek yanıtlanır.
nextCursorstr | None- `cursor` olarak geri geçirilecek id; son sayfada null olur. `iterate` ve `list_all`, bu değer null olduğunda veya `hasMore` false olduğunda durur; çünkü daha fazlası olduğunu söyleyip cursor vermeyen bir sayfa sonsuza dek döngüye girerdi.
items[].objectLiteral['email']- Bu listenin satırlarında her zaman `'email'`.
items[].idstr- Bu API'nin kendi id'si, `msg_…`. Diğer tüm emails uç noktalarının aldığı ve bir cursor'ın gösterdiği değer budur.
items[].statusEmailStatus- Mesajın yaşam döngüsünde nerede olduğu. `partial`, başarısızlığın bir türü değil kendi başına bir durumdur: bazı alıcılar mesajı almıştır ve bu geri alınamaz, dolayısıyla yeniden denemek yanlıştır. `bounced`, mesajın gönderildikten sonra her alıcıdan geri döndüğü, yani kimsenin almadığı anlamına gelir; `get` içindeki her alıcı nedenini söyler.
items[].modeApiKeyMode- `live` veya `test`; gönderen anahtardan alınır. Test gönderimi burada kaydedilir ve asla iletilmez.
items[].fromstr- Gönderimin yetkilendirildiği adres; çıplak ve küçük harfli olarak saklanır, dolayısıyla `from` alanında verilen bir görünen ad ağ üzerinde yine de gider ama burada tutulmaz. Sözlük değil düz dizgedir, çünkü bu, yetkilendirilmiş kimliktir: bir anahtarın gönderim kapsamı dışındaki, ne sahip olduğu bir alan adında bulunan ne de üzerinde adı geçen bir adres, sahip olduğu bir adresle sessizce değiştirilmez, 403 ile reddedilir.
items[].subjectstr | None- Saklandığı hâliyle konu. Konusuz kaydedilmiş bir mesajda null.
items[].messageIdstr | None- RFC 5322 Message-ID; bizim id'miz değil. MIME oluşana kadar null'dır ve gönderim servisi tarafından çıkışta yeniden yazılır; dolayısıyla sonraki bir geri dönüş veya DSN farklı bir id taşır ve bunun yerine `items[].id` üzerinden eşleştirilir.
items[].threadIdstr | None- Bu mesajın ait olduğu konuşma dizisi; bir dizi verilmiş veya atanmışsa. Aksi hâlde null.
items[].transportEmailTransport | str | None- Baytların nasıl gittiği. Gönderime kadar null'dır ve tipi açık bırakılmıştır; böylece bu SDK'nın henüz adlandırmadığı bir taşıma katmanı kırıcı bir değişiklik olmaz: saklanan kayıtlar artık kullanılmayan katmanları da adlandırabilir.
items[].attemptsint- Mesaj için kaç gönderim denemesi yapıldığı; ilkinden önce 0.
items[].lastErrorstr | None- En son gönderim hatası, bir insan için yazılmış. Hiçbir şey başarısız olmadıkça null.
items[].scheduledAtstr | None- Mesajın ne zaman gitmesi gerektiği, bir ISO-8601 anı olarak. Yalnızca iptal penceresi olmayan anlık bir gönderimde null olur: pencere kısa bir gecikmeden ibarettir, bu yüzden `cancellableForSeconds` de burayı doldurur; üstelik `status` değeri `scheduled` değil `queued` olan bir satırda.
items[].cancellableUntilstr | None- Mesajın gitmesi gereken an; ertelenmiş her gönderimde `scheduledAt` ile aynı değeri, ertelenmemiş bir gönderimde ise null taşır. Sunucunun yaptığı sınama değil, gösterilecek bir zaman damgasıdır: `cancel`, `status` üzerinden dallanır ve bir mesajı yalnızca hâlâ `queued` veya `scheduled` iken durdurur.
items[].sentAtstr | None- Ne zaman gittiği. Gönderim tamamlanana kadar null'dır; dallanılacak alanın bu değil `status` olmasının nedeni de budur.
items[].tagsdict[str, str]- Gönderimde verilen etiketler, olduğu gibi geri döndürülür ve hiçbir zaman yorumlanmaz. Her zaman bir sözlüktür (hiçbiri ayarlanmadıysa `{}`, asla null değil) ve yalnızca geri döndürülür: bu çağrı `status`, `from_`, `broadcast_id`, `scheduled_from` ve `scheduled_to` üzerinde filtreler, bu yüzden etiket bir mesajdan okunacak bir şeydir, onu bulmanın bir yolu değildir.
items[].broadcastIdstr | None- Bu iletinin kopyası olduğu `brd_` toplu gönderimi ya da tek başına gönderilmiş bir ileti için null.
items[].sourceEmailSource | str- Gönderimi hangi yüzeyin istediği: `composer`, `api`, `mcp`, `ai`, `oauth` veya `form`. `api`, bir API anahtarıyla çalışan bu istemcidir; `oauth` ise bir erişim tokenıyla çalışan bu istemcidir.
items[].createdAtstr- Gönderim kaydının ne zaman yazıldığı; bu, gönderimden öncedir. Listenin sıraladığı ve bir cursor'ın karşılaştırdığı alan budur.
items[].trackingNotRequired[EmailTrackingSummary]- Etkileşim özeti; yalnızca mesajı izlenmiş bir satırda bulunur, aksi hâlde hiç bulunmaz. “Bu izlendi mi?” sorusunun yanıtı yokluğudur; `openCount: 0` ise “kimse açmadı” diye okunurdu.
items[].tracking.opensbool- Bu mesajın bir pikselle gidip gitmediği. Hesap ayarının şu anda ne dediği değil, bu mesaja ne uygulandığı.
items[].tracking.clicksbool- Bu mesajın bağlantılarının yeniden yazılıp yazılmadığı. Gövdede yeniden yazılacak bağlantı yoksa false olur, çünkü o zaman hiçbir şey değiştirilmemiştir.
items[].tracking.openedbool- Sayılan herhangi bir açılma kaydedilip kaydedilmediği; `openCount > 0` ifadesinden türetilir.
items[].tracking.clickedbool- Sayılan herhangi bir tıklama kaydedilip kaydedilmediği; `clickCount > 0` ifadesinden türetilir.
items[].tracking.openCountint- Bir insanın yol açtığına inanılan açılmalar, mesajın her kopyası üzerinden toplanır. Tarayıcı botları ve gizlilik vekilleri kaydedilir ama hariç tutulur; otuz saniye içindeki tekrarlı istekler tek bir açılmaya indirgenir.
items[].tracking.clickCountint- Sayılan tıklamalar, kopyalar üzerinden toplanır. Mesaj başına değil bağlantı başına tekilleştirilir, çünkü saniyeler arayla iki bağlantıya tıklamak bir tekrar değil iki ayrı eylemdir.
items[].tracking.firstOpenAtstr | None- Kopyalar arasındaki en erken sayılan açılma; hiç yoksa null. Makine istekleri bunu asla değiştirmez.
items[].translationNotRequired[EmailTranslationResource]- Bir liste satırında asla bulunmaz: çeviri kaydı, listenin bilerek getirmediği saklanan istekte yer alır. Buradaki yokluğu, mesajın çevrilip çevrilmediği hakkında hiçbir şey söylemez. `get` çağrısına sorun.