ब्रॉडकास्ट

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

ब्रॉडकास्ट एक या अधिक ऑडियंस में सभी को एक संदेश भेजता है, हर व्यक्ति के लिए अलग कॉपी के रूप में। हर कॉपी का ठीक एक प्राप्तकर्ता होता है और कोई cc या bcc नहीं, इसलिए कोई नहीं देखता कि यह और किसे गई, और हर कॉपी अपनी msg_ id, इवेंट, ट्रैकिंग और वेबहुक वाला एक सामान्य ईमेल है। list_recipients उन्हें इस जानकारी के साथ सूचीबद्ध करता है कि हर एक के साथ क्या हुआ। कॉपियाँ Sent फ़ोल्डर में नहीं रखी जातीं, क्योंकि ब्रॉडकास्ट ही रिकॉर्ड है।

send ब्रॉडकास्ट को queued स्थिति में, या scheduledAt: पास करने पर scheduled में, तुरंत लौटाता है, और भेजना पृष्ठभूमि में चलता है। send को emails:send और audiences:read चाहिए, और preview को audiences:read। list, list_all, iterate, get, list_recipients, list_all_recipients, iterate_recipients, get_recipient, stats और analytics को emails:read चाहिए, और cancel को emails:send।

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]

ब्रॉडकास्ट के फ़ील्ड keyword arguments या एक Hash हैं, और API के camelCase नाम बनाए रखते हैं (audienceIds:, scheduledAt:)। idempotency_key: और api_key: कॉल के विकल्प हैं और कभी फ़ील्ड के रूप में नहीं भेजे जाते। Hash के साथ दिए keywords उसमें मिला दिए जाते हैं, इसलिए send(draft, scheduledAt: "P1D") वही ड्राफ़्ट एक दिन बाद भेजता है। scheduledAt: Time, DateTime, ISO 8601 स्ट्रिंग या PT2H जैसी अवधि लेता है, और Time UTC क्षण के रूप में जाता है। preview आपके दिए में से सिर्फ़ audienceIds भेजता है, इसलिए यह send वाला ही Hash लेता है। जवाब Symbol कुंजियों वाला Hash है, इसलिए broadcast[:status] status पढ़ता है।

subject, html और text हर व्यक्ति के लिए उसके संपर्क से भरे जाते हैं। {{firstName}} संपर्क के नाम का पहला शब्द है, {{lastName}} बाकी हिस्सा, {{name}} पूरा नाम, {{email}} वह पता जिस पर कॉपी जाती है और {{unsubscribeUrl}} वह लिंक जो उसकी सदस्यता छुड़ाता है।

हर फ़ील्ड बार के बाद एक फ़ॉलबैक लेता है, जो तब इस्तेमाल होता है जब संपर्क के पास उसका मान न हो, इसलिए बिना नाम सहेजे गए संपर्क के लिए {{firstName|there}} "there" बन जाता है। html में मान escape किए जाते हैं, और कोई भी दूसरा {{…}} ठीक वैसा ही छोड़ा जाता है जैसा लिखा है।

सहेजा गया टेम्पलेट भेजने के लिए html: और text: के बजाय template: पास करें, id और वैकल्पिक version, props तथा slots वाले Hash के रूप में। वही पाँच मान उस तक props के रूप में पहुँचते हैं, पर सिर्फ़ वे props जो टेम्पलेट घोषित करता है, इसलिए जो टेम्पलेट firstName घोषित करता है उसे वह मिलता है और जो नहीं करता उसे इसके लिए कभी अस्वीकार नहीं किया जाता। उसके props में जो कुछ भी हो वह हर कॉपी को एक जैसा जाता है।

हर कॉपी में एक-क्लिक सदस्यता छोड़ने के हेडर होते हैं जिनसे मेल क्लाइंट अपना सदस्यता छोड़ने का बटन दिखा पाता है, जो बड़े मेलबॉक्स प्रदाता थोक मेल से माँगते हैं। जो html या text मुख्य भाग ख़ुद {{unsubscribeUrl}} नहीं रखता उसे लिंक वाला एक पंक्ति का फ़ुटर मिलता है। टेम्पलेट ठीक वैसा ही भेजा जाता है जैसा है, इसलिए {{unsubscribeUrl}} टेम्पलेट में डालें।

सदस्यता छोड़ना व्यक्ति को उन सभी ऑडियंस में सदस्यता छोड़ चुका चिह्नित करता है जिन्हें वह ब्रॉडकास्ट गया था, और audiences.list_contacts इसे उसकी पंक्ति के unsubscribedAt में दिखाता है, जैसा “ऑडियंस” पेज बताता है। वह ऑडियंस में और पता-पुस्तिका में बना रहता है, उसकी दूसरी ऑडियंस अछूती रहती हैं, और उसे एक-एक करके भेजा गया मेल फिर भी जाता है। उसे ऑडियंस से निकालकर फिर जोड़ने से वह नए सिरे से सदस्य बन जाता है।

broadcast audienceIds में से कम से कम एक के हर संपर्क तक पहुँचता है, एक बार, चाहे कितनी भी उसे रखती हों। यह उस संपर्क को छोड़ता है जिसने उनमें से हर उस ऑडियंस की सदस्यता छोड़ दी है जिसमें वह है, और उस पते को जो बाउंस या शिकायत के बाद, या किसी के जोड़ने से, रोक सूची में है। send के बाद पर भेजना पहुँचने से पहले किसी ऑडियंस में जोड़े गए संपर्क को भी मिलता है।

preview बिना भेजे वही संख्याएँ लौटाता है: recipients, unsubscribed और suppressed। जो send किसी तक न पहुँचे वह OpenEmail::ValidationError के रूप में 422 no_recipients raise करता है।

get कॉपियों से counts लाइव पढ़ता है, इसलिए ब्रॉडकास्ट भेजे जाते समय इसे बार-बार पढ़ें, कॉलों के बीच sleep के साथ, जैसा ऊपर का नमूना करता है। status scheduled या queued से sending पर जाता है और जब सौंपी गई हर कॉपी निकल चुकी हो या विफल हो चुकी हो तो sent पर टिकता है। जब तक कॉपियाँ अभी इंतज़ार में हैं यह sending रहता है, completedAt के यह बताने के बाद भी कि आख़िरी व्यक्ति तक पहुँच हो गई। failed का मतलब है कि पूरा ब्रॉडकास्ट रुक गया, और lastError बताता है क्यों: from पते से अब भेजा नहीं जा सकता, टेम्पलेट resolve होना बंद हो गया, प्लान बीच में ख़त्म हो गया, भेजना ख़ुद बार-बार विफल होता रहा, या एक भी कॉपी लिखी नहीं जा सकी।

cancel उस ब्रॉडकास्ट को रोकता है जो scheduled, queued या sending है। कोई और नहीं जोड़ा जाता और अभी इंतज़ार कर रही हर कॉपी रद्द हो जाती है, जबकि जा चुकी कॉपियाँ वापस नहीं बुलाई जा सकतीं। जब हर कॉपी जा चुकी हो, तो cancel OpenEmail::ConflictError के रूप में 409 broadcast_not_cancellable raise करता है, और रद्द ब्रॉडकास्ट को रद्द करने पर वह जैसा है वैसा लौटता है।

list_recipients उन लोगों का एक OpenEmail::Page लौटाता है जिन्हें ब्रॉडकास्ट गया, हर कॉपी के लिए एक पंक्ति, पते के क्रम में, items, has_more? और next_cursor के साथ। list_all_recipients हर पेज पर चलकर एक Array बनाता है, और iterate_recipients एक बार में एक कॉपी block में yield करता है, अगला पेज तभी लाते हुए जब लूप माँगे। block के बिना यह एक Enumerator लौटाता है। limit: 1 से 200 तक जाता है और डिफ़ॉल्ट 50 है, और cursor: उन्हीं filter: और q: के साथ वापस जाता है।

OpenEmail::BROADCAST_RECIPIENT_FILTERS हर फ़िल्टर का नाम बताता है, और q: case को अनदेखा करते हुए पता और नाम खोजता है। opens और clicks image proxies और link scanners को छोड़ देते हैं, और जब ब्रॉडकास्ट ट्रैकिंग बंद रखकर गया हो तो 0 रहते हैं।

get_recipient(id, email_id) एक कॉपी लौटाता है: वही पंक्ति, साथ में subject, html और text ठीक वैसे जैसे उस व्यक्ति को मिले, merge फ़ील्ड भरे हुए और उसके अपने unsubscribe लिंक के साथ। किसी पंक्ति का emailId email_id के रूप में पास करें। HTML open और click ट्रैकिंग जोड़े जाने से पहले का है। जो email_id इस ब्रॉडकास्ट की कॉपी नहीं है वह 404 recipient_not_found raise करता है, और अज्ञात ब्रॉडकास्ट 404 broadcast_not_found, दोनों OpenEmail::NotFoundError के रूप में।

stats कुल योग और एक series लौटाता है। totals sent, delivered, bounced, complained और failed कॉपियाँ गिनता है, अभी इंतज़ार कर रही कॉपियों के लिए pending के साथ, और उन लोगों को जिन्होंने opened, clicked और unsubscribed किया, opens और clicks इवेंट गिनती के रूप में। series विरल है और सबसे पुराना पहले, हर grain: (minute, hour या day, डिफ़ॉल्ट hour) के लिए एक बकेट जिसमें कुछ हुआ, उस zone में काटा गया जो UTC से offset_minutes: पूर्व में है। स्थानीय zone के लिए Time.now.utc_offset / 60 पास करें। यह हर व्यक्ति को एक बार गिनता है, उस पहले समय पर जब उसके साथ यह हुआ, इसलिए इसका जोड़ कुल योग के बराबर आता है।

हाल में क्या हुआ यह भी पढ़ने के लिए stats को days: या minutes: पास करें। तब window उसके भीतर डिलीवर, bounce, spam के रूप में रिपोर्ट, खोले गए, क्लिक किए गए और सदस्यता छोड़ने वालों को गिनता है, और series सिर्फ़ उसके बकेट रखता है, जबकि totals अब भी पूरे ब्रॉडकास्ट को कवर करता है। दोनों में से कोई न हो तो window nil है।

send, get और cancel हर एक इनमें से एक लौटाते हैं, Symbol कुंजियों वाला Hash, और send replayed जोड़ता है। list इनका एक OpenEmail::Page लौटाता है, सबसे नए पहले, और list_all तथा iterate हर पेज पर चलते हैं। preview audienceIds, recipients, unsubscribed और suppressed वाला Hash लौटाता है। list_recipients प्राप्तकर्ता पंक्तियों का एक OpenEmail::Page लौटाता है, get_recipient एक पंक्ति उसकी सामग्री के साथ लौटाता है, और stats broadcastId, grain, totals, window और series वाला Hash लौटाता है। analytics totals, series और broadcasts में हर ब्रॉडकास्ट की एक पंक्ति वाला Hash लौटाता है। समय ISO 8601 स्ट्रिंग हैं, जिन्हें Time.iso8601 पार्स करता है।

list_recipients, list_all_recipients और iterate_recipients की हर पंक्ति, Symbol कुंजियों वाले Hash के रूप में। get_recipient जो Hash लौटाता है वह subject, html और text जोड़ता है।