Ruby

Listeleme ve getirme

`emails.list`, `emails.list_all`, `emails.iterate`, `emails.get` ve `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

Bir sayfa, items, has_more? ve next_cursor içeren bir OpenEmail::Page nesnesidir. Sonraki sayfa için next_cursor değerini aynı filtrelerle cursor: olarak geri geçirin.

emails.iterate ve 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

İkisi de next_cursor değerini sizin için izler. iterate bir sayfayı yalnızca dolaşma oraya ulaştığında getirir; bu yüzden bloktaki break ya da blok olmadan döndürdüğü Enumerator üzerindeki first veya find istekleri durdurur. list_all ise tek bir Array döndürmeden önce her sayfayı dolaşır, bu yüzden ona sonu olan bir filtre verin. Her iki durumda da anahtar kümesine dayalı (keyset) sayfalama kullanılır; böylece dolaşma sırasında gelen bir ileti, bir ofsetin yapacağı gibi bir satırın atlanmasına yol açamaz.

emails.get ve 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]}" }

recipients döndüren tek çağrı get'tir: her adres için kendi status, error ve deliveredAt değerlerine sahip bir Hash. Her biri alıcılarını taşıyan elli iletilik bir liste, kimsenin istemediği bir rapor sayfası olurdu.

list_events bir gönderimin olay geçmişini en eskiden başlayarak okur: email.accepted, email.queued, email.sent, email.delivered, email.bounced, email.opened ve diğerleri; her biri biçimi type değerine bağlı olan bir data Hash'i içerir. list_all_events ve iterate_events geçmişin tamamını sizin için dolaşır. Webhook'lar aynı olayların bir alt kümesini gerçekleştikçe teslim eder; bu yüzden bir webhook kaçırıldığında bakılacak yer burasıdır.

Parametreler

statusString or Array<String>: Bir ya da birkaç durum (`queued`, `scheduled`, `sending`, `sent`, `partial`, `bounced`, `cancelled`, `failed`); verilenlerden herhangi biriyle eşleşir. `bounced`, iletinin gittiği her alıcıda geri döndüğü anlamına gelir; bazılarında geri dönüp diğerlerine ulaşan bir ileti ise `partial` olarak görünür. Sunucu virgüllere göre böldüğü için gem bir Array'i virgülle ayrılmış tek bir değer olarak gönderir ve küme dışındaki bir değer, bilinmeyeni adlandıran bir 422 verir.
broadcast_idString: Yalnızca tek bir toplu gönderimin kopyaları; `broadcasts.send` çağrısından gelen bir `brd_` kimliği. Bir toplu gönderimin ulaştığı her kişi kendine ait bir ileti alır; bu yüzden bu liste, gönderimin kime gittiğini ve her kopyaya ne olduğunu gösterir. `broadcasts.list_recipients` aynı kişileri açılmaları, tıklamaları ve abonelikten çıkmalarıyla birlikte listeler.
fromString: Kaydedildiği hâliyle, yani küçük harfe çevrilmiş çıplak `addr@host` olarak gönderen adresle tam eşleşme. Kayıt, görünen ad çıkarılarak yazılır; bu yüzden `Acme <[email protected]>` gibi açılı ayraçlı bir adres hiçbir şeyle eşleşmez. Değeriniz karşılaştırmadan önce küçük harfe çevrilir ve bu bir önek ya da alan adı eşleşmesi değil, eşitlik karşılaştırmasıdır.
scheduled_fromTime, DateTime or String: Yalnızca bu an ya da sonrası için zamanlanmış iletiler. `scheduled_to:` ve `status: ["scheduled", "queued"]` ile birlikte, uygulamanın takviminin yaptığı gibi bir zaman aralığında gönderilmeyi bekleyenleri listeler. `scheduledAt` değeri olmayan bir ileti dışarıda kalır. Bir Time, bir DateTime ya da ofsetiyle birlikte bir ISO 8601 anı geçirin: bir Ruby Date çıplak bir tarih olarak gönderilir ve bu iki filtre onu reddeder.
scheduled_toTime, DateTime or String: Yalnızca bu an ya da öncesi için zamanlanmış iletiler. `scheduled_to:` değerinden sonra gelen bir `scheduled_from:` 422 `invalid_parameter` verir.
limitInteger: Bu sayfadaki satır sayısı; 1 ile 100 arası, varsayılanı 25. Bu aralığın dışındaki bir değer kırpılmaz, 422 ile reddedilir. `list_all` ve `iterate` üzerinde, getirdikleri her sayfanın boyutudur.
cursorString: Sayfalamaya başlanacak ileti kimliği (`msg_…`). Ofset değil, anahtar kümesi (keyset): satırlar o iletinin `createdAt` değerinden kesinlikle daha eski olarak döner; böylece sayfa ortasında gelen gönderimler bir satırı sizden öteye itemez. Bu çalışma alanındaki hiçbir iletiyi belirtmeyen bir kimlik 400 `invalid_cursor` verir.
api_keyString: İstemcinin anahtarı yerine bu anahtarla listeler.

Bazı adreslere daraltılmış bir anahtar yalnızca kapsadığı adreslerden gönderilen iletileri okur ve sayfa bu filtreden sonra kesilir; bu yüzden sonuncusu dışındaki her sayfa yine de limit kadar satır içerir. Anahtarın kapsamadığı bir from: 403 yerine boş bir son sayfa döndürür.

Yanıt: OpenEmail::Page

itemsArray<Hash>: `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.
has_more?Boolean: 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.
next_cursorString or nil: `cursor:` olarak geri geçirilecek kimlik; son sayfada nil. `iterate` ve `list_all`, bu değer nil olduğunda ya da `has_more?` false olduğunda durur, çünkü devamı olduğunu iddia edip hiçbir cursor belirtmeyen bir sayfa sonsuza dek döngüye girerdi.

Her öğe

objectString: Bu listenin bir satırında her zaman `email`.
idString: Bu API'nin kendi kimliği, `msg_…`. Diğer tüm emails çağrılarının aldığı ve bir cursor'ın belirttiği değer budur.
statusString: 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.
modeString: `live` veya `test`; gönderen anahtardan alınır. Test gönderimi burada kaydedilir ve asla iletilmez.
fromString: Gönderimin yetkilendirildiği adres; çıplak ve küçük harfe çevrilmiş olarak saklanır, bu yüzden `from` üzerinde verilen bir görünen ad ağa yine gider ama burada tutulmaz. Hash değil düz bir String'dir, çünkü bu yetkilendirilmiş kimliktir: bir anahtarın gönderim kapsamı dışındaki, ne sahip olduğu bir alan adında olan ne de anahtarda adı geçen bir adres 403 ile reddedilir; asla sessizce kapsamdaki bir adresle değiştirilmez.
subjectString or nil: Saklandığı hâliyle konu. Konusuz kaydedilmiş bir iletide nil.
messageIdString or nil: Bizim kimliğimiz değil, RFC 5322 Message-ID. MIME oluşana kadar nil'dir ve gönderim hizmeti tarafından çıkışta yeniden yazılır; bu yüzden daha sonraki bir geri dönme ya da DSN farklı bir kimlik taşır ve bunun yerine `id` ile ilişkilendirilir.
threadIdString or nil: Verilmiş ya da atanmışsa bu iletinin ait olduğu konuşma dizisi. Aksi hâlde nil.
transportString or nil: Baytların nasıl çıktığı. Sevk edilene kadar nil. Saklanan kayıtlar artık kullanılmayan taşıma katmanlarını hâlâ adlandırabilir; bu yüzden bilmediğiniz bir değeri bir hata olarak değil, bir bilgi olarak ele alın.
attemptsInteger: Mesaj için kaç gönderim denemesi yapıldığı; ilkinden önce 0.
lastErrorString or nil: Bir insan için yazılmış en son sevk hatası. Hiçbir şey başarısız olmadıkça nil.
scheduledAtString or nil: İletinin çıkması gereken an, ISO 8601 anı olarak. Yalnızca iptal penceresi olmayan anında bir gönderimde nil: pencere kısa bir gecikmeden başka bir şey değildir, bu yüzden `cancellableForSeconds` de bu alanı doldurur; bu durumda satırın `status` değeri `scheduled` değil, `queued` olur.
cancellableUntilString or nil: İletinin çıkması gereken an; ertelenmiş her gönderimde `scheduledAt` ile aynı değeri taşır, ertelenmemiş olanda nil'dir. Sunucunun yaptığı denetim değil, gösterilecek bir zaman damgasıdır: `cancel` dallanmayı `status` değerine göre yapar ve bir iletiyi yalnızca hâlâ `queued` ya da `scheduled` iken durdurur.
sentAtString or nil: İletinin gittiği an. Sevk tamamlanana kadar nil'dir; dallanma için bu alanın değil, `status` alanının kullanılmasının nedeni budur.
tagsHash: Gönderimde verilen etiketler; olduğu gibi geri döndürülür ve asla yorumlanmaz. Her zaman bir Hash'tir (hiçbiri ayarlanmadıysa boş, asla nil değil) ve yalnızca geri döndürülür: bu liste `status`, `from`, `broadcast_id` ve zamanlama penceresine göre filtreler; bu yüzden bir etiket, bir iletiyi bulmanın yolu değil, iletiden okunacak bir şeydir.
broadcastIdString or nil: Bu iletinin kopyalarından biri olduğu `brd_` toplu gönderimi; tek başına gönderilmiş bir ileti için nil.
sourceString: Gönderimi hangi yüzeyin istediği: `composer`, `api`, `mcp`, `ai` veya `queue`. `api` bu istemcidir.
createdAtString: 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.
trackingHash: Etkileşim özeti; yalnızca iletisi izlenmiş bir satırda bulunur, diğerlerinde yoktur. Yokluğu “bu izlendi mi” sorusunun yanıtıdır; 0 değerindeki bir `openCount` ise “kimse açmadı” olarak okunurdu.
translationHash: 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.

Bir öğenin izlemesi

opensBoolean: Bu mesajın bir pikselle gidip gitmediği. Hesap ayarının şu anda ne dediği değil, bu mesaja ne uygulandığı.
clicksBoolean: Bu iletinin bağlantılarının yeniden yazılıp yazılmadığı. Gövdede yeniden yazılacak bağlantı yoksa false, çünkü o durumda hiçbir şey değişmemiştir.
openedBoolean: Sayılan herhangi bir açılmanın kaydedilip kaydedilmediği; 0'dan büyük `openCount` değerinden türetilir.
clickedBoolean: Sayılan herhangi bir tıklamanın kaydedilip kaydedilmediği; 0'dan büyük `clickCount` değerinden türetilir.
openCountInteger: 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.
clickCountInteger: 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.
firstOpenAtString or nil: Kopyalar genelinde sayılan en erken açılma; hiç yokken nil. Makine erişimleri onu asla değiştirmez.