ब्रॉडकास्ट

use OpenEmail\Constants\BroadcastRecipientFilters;use OpenEmail\Constants\BroadcastStatuses; $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);echo $reach['recipients'], ' ', $reach['unsubscribed'], ' ', $reach['suppressed'], PHP_EOL; $broadcast = $client->broadcasts->send($draft); $latest = $client->broadcasts->get($broadcast['id']); while (in_array($latest['status'], [BroadcastStatuses::SCHEDULED, BroadcastStatuses::QUEUED, BroadcastStatuses::SENDING], true)) {    sleep(5);    $latest = $client->broadcasts->get($broadcast['id']);} foreach ($client->broadcasts->iterateRecipients($broadcast['id']) as $copy) {    echo $copy['email'], ' ', $copy['status'], ' ', $copy['opens'], ' ', $copy['clicks'], PHP_EOL;} $bounced = $client->broadcasts->listRecipients($broadcast['id'], filter: BroadcastRecipientFilters::BOUNCED); foreach ($bounced as $row) {    echo $row['emailId'], ' ', $row['email'], PHP_EOL;} $copy = $client->broadcasts->getRecipient($broadcast['id'], 'msg_01dad25067bc4dac966d515d');echo $copy['subject'], ' ', $copy['bouncedAt'] ?? 'not bounced', PHP_EOL; $stats = $client->broadcasts->stats($broadcast['id'], grain: 'day');echo $stats['totals']['opened'], ' ', $stats['totals']['clicked'], ' ', $stats['totals']['unsubscribed'], PHP_EOL; $lately = $client->broadcasts->stats($broadcast['id'], days: 1);echo $lately['window']['opened'] ?? 0, PHP_EOL; $later = $client->broadcasts->send([...$draft, 'scheduledAt' => 'P1D']);$client->broadcasts->cancel($later['id']); $history = $client->broadcasts->list(audienceId: $draft['audienceIds'][0]);echo $latest['status'], ' ', $latest['counts']['sent'], ' ', count($history), PHP_EOL; $month = $client->broadcasts->analytics(days: 30); foreach ($month['broadcasts'] as $row) {    echo $row['subject'], ' ', $row['sent'], ' ', $row['opened'], PHP_EOL;}

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

send तुरंत queued ब्रॉडकास्ट के साथ लौटता है, या जब बॉडी में scheduledAt हो तो scheduled के साथ, और भेजना पृष्ठभूमि में चलता है। send को emails:send और audiences:read चाहिए, और preview को audiences:read। list, listAll, iterate, get, listRecipients, listAllRecipients, iterateRecipients, getRecipient, 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' => new \DateTimeImmutable('+1 hour'),], idempotencyKey: 'doors-open-2026-10'); echo $broadcast['id'], ' ', $broadcast['status'], ' ', $broadcast['replayed'] ? 'replayed' : 'new', PHP_EOL;

ब्रॉडकास्ट के फ़ील्ड API के camelCase नामों वाले एक array की कुंजियाँ हैं (audienceIds, scheduledAt)। idempotencyKey: और apiKey: कॉल के named आर्ग्युमेंट हैं और कभी फ़ील्ड के रूप में नहीं भेजे जाते। किसी ड्राफ़्ट को एक फ़ील्ड के साथ नए array में फैलाने से वही ड्राफ़्ट उस एक बदलाव के साथ भेजा जाता है, इसलिए send([...$draft, 'scheduledAt' => 'P1D']) उसे एक दिन बाद भेजता है। scheduledAt एक DateTimeInterface, ISO 8601 स्ट्रिंग या PT2H जैसी अवधि लेता है, और DateTimeInterface UTC क्षण के रूप में जाता है। preview आपके दिए हुए में से सिर्फ़ audienceIds भेजता है, इसलिए वह send जैसा ही array लेता है। जवाब camelCase कुंजियों वाला array है, इसलिए $broadcast['status'] status पढ़ता है।

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

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

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

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

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

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

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

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

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

listRecipients उन लोगों का एक OpenEmail\Result\Page लौटाता है जिन्हें ब्रॉडकास्ट गया, हर कॉपी के लिए एक पंक्ति, पते के अनुसार क्रमबद्ध, items, hasMore और nextCursor के साथ। listAllRecipients हर पेज पर चलकर एक array बनाता है, और iterateRecipients एक Generator लौटाता है जो एक बार में एक कॉपी yield करता है और अगला पेज तभी लाता है जब लूप माँगे। limit: 1 से 200 तक होता है और डिफ़ॉल्ट 50 है, और cursor: उन्हीं filter: और q: के साथ वापस भेजा जाता है।

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

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

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

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

send, get और cancel में से हर एक इनमें से एक को camelCase कुंजियों वाले array के रूप में लौटाता है, और send replayed जोड़ता है। list इनका एक OpenEmail\Result\Page लौटाता है, सबसे नया पहले, listAll हर एक को एक array में लौटाता है और iterate इन पर एक Generator लौटाता है। preview audienceIds, recipients, unsubscribed और suppressed वाला array लौटाता है। listRecipients प्राप्तकर्ता पंक्तियों का एक Page लौटाता है, getRecipient अपनी सामग्री के साथ एक पंक्ति लौटाता है, और stats broadcastId, grain, totals, window और series वाला array लौटाता है। analytics totals, series और broadcasts में हर ब्रॉडकास्ट की एक पंक्ति वाला array लौटाता है। समय ISO 8601 स्ट्रिंग हैं, जिन्हें new \DateTimeImmutable() पढ़ता है।

listRecipients, listAllRecipients और iterateRecipients की हर पंक्ति, camelCase कुंजियों वाले array के रूप में। getRecipient जो array लौटाता है उसमें subject, html और text जुड़ते हैं।