Toplu gönderimler

draft = {  audienceIds: ["aud_4c1b8e2a7d9f05c36b4e8a71"],  from: "Acme <[email protected]>",  subject: "{{firstName|Hello}}, the September release is out",  html: "<p>Hi {{firstName|there}},</p><p>Here is what changed this month.</p>",  text: "Hi {{firstName|there}}, here is what changed this month. Unsubscribe: {{unsubscribeUrl}}",  tags: {campaign: "release-2026-09"}} reach = client.broadcasts.preview(draft)puts reach[:recipients], reach[:unsubscribed], reach[:suppressed] broadcast = client.broadcasts.send(draft) latest = client.broadcasts.get(broadcast[:id])while %w[scheduled queued sending].include?(latest[:status])  sleep 5  latest = client.broadcasts.get(broadcast[:id])end client.broadcasts.iterate_recipients(broadcast[:id]) do |copy|  puts copy[:email], copy[:status], copy[:opens], copy[:clicks]end bounced = client.broadcasts.list_recipients(broadcast[:id], filter: "bounced")bounced.items.each { |row| puts "#{row[:emailId]} #{row[:email]}" } copy = client.broadcasts.get_recipient(broadcast[:id], "msg_01dad25067bc4dac966d515d")puts copy[:subject], copy[:bouncedAt] stats = client.broadcasts.stats(broadcast[:id], grain: "day")puts stats.dig(:totals, :opened), stats.dig(:totals, :clicked), stats.dig(:totals, :unsubscribed) lately = client.broadcasts.stats(broadcast[:id], days: 1)puts lately.dig(:window, :opened) later = client.broadcasts.send(draft, scheduledAt: "P1D")client.broadcasts.cancel(later[:id]) history = client.broadcasts.list(audience_id: draft[:audienceIds].first)puts latest[:status], latest.dig(:counts, :sent), history.items.size month = client.broadcasts.analytics(days: 30)month[:broadcasts].each do |row|  puts row[:subject], row[:sent], row[:opened]end

Toplu gönderim, bir ya da daha fazla kitledeki herkese her kişi için ayrı bir kopya olarak tek bir ileti gönderir. Her kopyanın tam olarak bir alıcısı vardır, cc ya da bcc yoktur; bu yüzden kimse başka kime gittiğini görmez ve her kopya kendi msg_ kimliği, olayları, izlemesi ve webhook'larıyla sıradan bir e-postadır. list_recipients bunları her birine ne olduğuyla birlikte listeler. Kopyalar Gönderilenler klasörüne konmaz, çünkü kaydın kendisi toplu gönderimdir.

send, toplu gönderim queued durumunda (ya da scheduledAt: geçirdiğinizde scheduled durumunda) olarak hemen döner ve gönderim arka planda çalışır. send, emails:send ve audiences:read gerektirir; preview ise audiences:read gerektirir. list, list_all, iterate, get, list_recipients, list_all_recipients, iterate_recipients, get_recipient, stats ve analytics emails:read, cancel ise emails:send gerektirir.

broadcast = client.broadcasts.send(  audienceIds: ["aud_4c1b8e2a7d9f05c36b4e8a71"],  from: "Acme <[email protected]>",  subject: "Doors open on Friday",  text: "Hi {{firstName|there}}, doors open at nine. Unsubscribe: {{unsubscribeUrl}}",  scheduledAt: Time.now + 3600,  idempotency_key: "doors-open-2026-10") puts broadcast[:id], broadcast[:status], broadcast[:replayed]

Bir toplu gönderimin alanları anahtar kelime argümanları ya da tek bir Hash'tir ve API'nin camelCase adlarını korur (audienceIds:, scheduledAt:). idempotency_key: ve api_key: çağrının seçenekleridir ve asla alan olarak gönderilmez. Bir Hash'in yanında geçirilen anahtar kelimeler onunla birleştirilir; bu yüzden send(draft, scheduledAt: "P1D") aynı taslağı bir gün sonra gönderir. scheduledAt: bir Time, bir DateTime, bir ISO 8601 dizesi ya da PT2H gibi bir süre alır ve bir Time bir UTC anı olarak gider. preview ona verdiklerinizden yalnızca audienceIds gönderir; bu yüzden send ile aynı Hash'i alır. Bir yanıt Symbol anahtarlı bir Hash'tir; bu yüzden broadcast[:status] durumu okur.

subject, html ve text her kişi için kendi kişi kaydından doldurulur. {{firstName}} kişi adının ilk sözcüğü, {{lastName}} geri kalanı, {{name}} tam ad, {{email}} kopyanın gittiği adres ve {{unsubscribeUrl}} onun aboneliğini sonlandıran bağlantıdır.

Her alan çizgiden sonra bir yedek değer alır; kişinin o alan için değeri yoksa kullanılır, bu yüzden {{firstName|there}} adsız kaydedilmiş bir kişi için "there" olur. Değerler html içinde kaçırılır ve diğer her {{…}} tam yazıldığı gibi bırakılır.

Kayıtlı bir şablonu göndermek için html: ve text: yerine, id ve isteğe bağlı version, props ve slots içeren bir Hash olarak template: geçirin. Aynı beş değer ona props olarak ulaşır, ancak yalnızca şablonun bildirdiği props; bu yüzden firstName bildiren bir şablon onu alır, bildirmeyen ise bu yüzden asla reddedilmez. props içindeki her şey her kopyaya aynı şekilde gider.

Her kopya, bir posta istemcisinin kendi abonelikten çıkma düğmesini göstermesini sağlayan tek tık abonelikten çıkma başlıklarını taşır; büyük posta kutusu sağlayıcılarının toplu postadan istediği de budur. {{unsubscribeUrl}}'i kendisi yerleştirmeyen bir html ya da text gövdesine bağlantıyı içeren tek satırlık bir alt bilgi eklenir. Şablon tam olduğu gibi gönderilir, bu yüzden {{unsubscribeUrl}}'i şablona koyun.

Abonelikten çıkmak, kişiyi o toplu gönderimin gittiği her kitlede abonelikten çıkmış olarak işaretler ve Kitleler sayfasında anlatıldığı gibi audiences.list_contacts bunu kişinin satırındaki unsubscribedAt alanında gösterir. Kişi kitlede ve adres defterinde kalır, diğer kitlelerine dokunulmaz ve ona tek tek gönderilen postalar gitmeye devam eder. Onu kitleden çıkarıp yeniden eklemek yeniden abone yapar.

Toplu gönderim, audienceIds içindekilerden en az birinde bulunan her kişiye, kaçında bulunursa bulunsun bir kez ulaşır. İçinde bulunduğu bu kitlelerin her birinden abonelikten çıkmış kişiyi ve bir geri dönme ya da şikâyet sonrasında veya biri eklediği için engelleme listesinde olan adresi atlar. send'den sonra ama gönderim ona ulaşmadan önce kitlelerden birine eklenen kişi dahil edilir.

preview göndermeden aynı sayıları döndürür: recipients, unsubscribed ve suppressed. Hiç kimseye ulaşmayacak bir send, OpenEmail::ValidationError olarak 422 no_recipients fırlatır.

get, counts değerini kopyalardan canlı okur; bu yüzden bir toplu gönderim sürerken, yukarıdaki örnekte olduğu gibi çağrılar arasında sleep ile onu yoklayın. status, scheduled ya da queued durumundan sending durumuna geçer ve devredilen her kopya gittiğinde ya da başarısız olduğunda sent durumuna oturur. completedAt son kişiye ulaşıldığını söyledikten sonra bile kopyalar hâlâ bekliyorsa sending olarak kalır. failed toplu gönderimin tamamının durduğu anlamına gelir ve lastError nedenini söyler: from adresinden artık gönderim yapılamıyordur, şablon çözümlenemez olmuştur, plan yarı yolda tükenmiştir, gönderimin kendisi sürekli başarısız olmuştur ya da tek bir kopya bile yazılamamıştır.

cancel, scheduled, queued ya da sending durumundaki bir toplu gönderimi durdurur. Başka kimse eklenmez ve hâlâ bekleyen her kopya iptal edilir; gitmiş kopyalar ise geri çağrılamaz. Her kopya gittikten sonra cancel, OpenEmail::ConflictError olarak 409 broadcast_not_cancellable fırlatır; iptal edilmiş bir toplu gönderimi iptal etmek ise onu olduğu gibi döndürür.

list_recipients, bir toplu gönderimin gittiği kişilerden oluşan, kopya başına bir satır içeren, adrese göre sıralanmış ve items, has_more? ile next_cursor içeren bir OpenEmail::Page döndürür. list_all_recipients her sayfayı dolaşarak tek bir Array oluşturur, iterate_recipients ise kopyaları birer birer bir bloğa verir ve bir sonraki sayfayı yalnızca döngü istediğinde getirir. Blok olmadan bir Enumerator döndürür. limit: 1 ile 200 arasıdır ve varsayılanı 50'dir; bir cursor: aynı filter: ve q: ile geri gönderilir.

OpenEmail::BROADCAST_RECIPIENT_FILTERS her filtreyi adlandırır; q: ise büyük/küçük harfi yok sayarak adreste ve adda arar. Açılmalar ve tıklamalar görsel proxy'lerini ve bağlantı tarayıcılarını dışarıda bırakır ve toplu gönderim izleme kapalıyken gittiyse 0 olarak kalır.

get_recipient(id, email_id) tek bir kopya döndürür: aynı satır ve ek olarak, birleştirme alanları doldurulmuş ve kişinin kendi abonelikten çıkma bağlantısıyla, o kişinin aldığı hâliyle subject, html ve text. Bir satırın emailId değerini email_id olarak geçirin. HTML, açılma ve tıklama izlemesi eklenmeden önceki hâlidir. Bu toplu gönderimin kopyası olmayan bir email_id 404 recipient_not_found, bilinmeyen bir toplu gönderim ise 404 broadcast_not_found fırlatır; ikisi de OpenEmail::NotFoundError olarak.

stats toplamları ve bir seri döndürür. totals; sent, delivered, bounced, complained ve failed kopyalarını, hâlâ bekleyenler için pending değerini ve opened, clicked ve unsubscribed olan kişileri sayar; opens ve clicks ise olay sayılarıdır. series seyrektir ve en eskiden başlar: bir şey olan her grain: (minute, hour ya da day, varsayılanı hour) için bir aralık; aralıklar UTC'nin offset_minutes: kadar doğusundaki saat dilimine göre kesilir. Yerel saat dilimi için Time.now.utc_offset / 60 geçirin. Her kişiyi, olay onun başına ilk geldiği anda bir kez sayar; bu yüzden toplamı totals ile tutar.

Son zamanlarda ne olduğunu da okumak için stats çağrısına days: ya da minutes: geçirin. Bu durumda window, pencere içinde teslim edileni, geri döneni, spam olarak bildirileni, açılanı, tıklananı ve abonelikten çıkılanı sayar; series yalnızca o pencerenin aralıklarını tutar, totals ise yine toplu gönderimin tamamını kapsar. İkisi de yoksa window nil'dir.

send, get ve cancel her biri bunlardan birini Symbol anahtarlı bir Hash olarak döndürür; send ayrıca replayed ekler. list bunlardan oluşan, en yeniden eskiye bir OpenEmail::Page döndürür; list_all ve iterate her sayfayı dolaşır. preview, audienceIds, recipients, unsubscribed ve suppressed içeren bir Hash döndürür. list_recipients alıcı satırlarından oluşan bir OpenEmail::Page, get_recipient içeriğiyle birlikte tek bir satır, stats ise broadcastId, grain, totals, window ve series içeren bir Hash döndürür. analytics, totals, series ve broadcasts içinde her toplu gönderim için bir satır içeren bir Hash döndürür. Zamanlar, Time.iso8601 ile ayrıştırılabilen ISO 8601 dizeleridir.

list_recipients, list_all_recipients ve iterate_recipients çağrılarının her satırı, Symbol anahtarlı bir Hash olarak. get_recipient çağrısının döndürdüğü Hash ayrıca subject, html ve text ekler.