ऑडियंस को भेजें
एक या अधिक ऑडियंस में सभी को एक संदेश भेजता है, हर व्यक्ति के लिए अलग कॉपी के रूप में और हर संपर्क से वैयक्तिकृत। हर कॉपी का ठीक एक प्राप्तकर्ता होता है और कोई cc या bcc नहीं, इसलिए कोई नहीं देखता कि यह और किसे गई, और हर कॉपी अपने `msg_` id, events, ट्रैकिंग और webhooks वाला सामान्य ईमेल है। कॉल तुरंत `202` देता है और भेजना बैकग्राउंड में चलता है, इसलिए इसे `GET /broadcasts/{id}` से देखें।
असली कॉल आपकी अपनी कुंजी से आपके वर्कस्पेस पर चलाता है।
POST /broadcasts
एक या अधिक ऑडियंस में सभी को एक संदेश भेजता है, हर व्यक्ति के लिए अलग कॉपी के रूप में और हर संपर्क से वैयक्तिकृत। हर कॉपी का ठीक एक प्राप्तकर्ता होता है और कोई cc या bcc नहीं, इसलिए कोई नहीं देखता कि यह और किसे गई, और हर कॉपी अपने msg_ id, events, ट्रैकिंग और webhooks वाला सामान्य ईमेल है। कॉल तुरंत 202 देता है और भेजना बैकग्राउंड में चलता है, इसलिए इसे GET /broadcasts/{id} से देखें।
उदाहरण
emails:send और audiences:read चाहिए। audienceIds में 1 से 10 id होते हैं। मुख्य भाग html और/या text से, या सहेजे गए template से आता है, दोनों से कभी नहीं, और subject ज़रूरी है जब तक टेम्पलेट उसे न दे।
curl -X POST "$OE/broadcasts" -H "$AUTH" -H 'content-type: application/json' -d '{ "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" }, "scheduledAt": "PT2H"}'{ "object": "broadcast", "id": "brd_5a8c1e3f7b2d94a06c8e1f3b", "status": "scheduled", "mode": "live", "source": "api", "audienceIds": ["aud_4c1b8e2a7d9f05c36b4e8a71"], "from": "Acme <[email protected]>", "subject": "{{firstName|Hello}}, the September release is out", "counts": { "recipients": 412, "created": 0, "skipped": 0, "failedToQueue": 0, "queued": 0, "sending": 0, "sent": 0, "failed": 0, "cancelled": 0 }, "lastError": null, "scheduledAt": "2026-09-23T14:00:00.000Z", "startedAt": null, "completedAt": null, "cancelledAt": null, "createdAt": "2026-09-23T12:00:00.000Z", "updatedAt": "2026-09-23T12:00:00.000Z", "replayed": false}जवाब queued है, या scheduledAt के साथ scheduled, जो ISO 8601 समय या PT2H जैसी अवधि लेता है, ज़्यादा से ज़्यादा 365 दिन आगे। counts.recipients अभी लिया गया अनुमान है, और बाकी गिनतियाँ 0 से शुरू होती हैं। Location हेडर broadcast का नाम देता है।
Idempotency-Key हेडर के साथ दोबारा कोशिश सुरक्षित है: वही key 200 के साथ पहले कॉल से बना broadcast और Idempotency-Replayed: true लौटाती है, और अलग मुख्य भाग के साथ वही key 422 idempotency_key_reuse है। key के बिना एक ही मुख्य भाग दो बार भेजने से broadcast दो बार जाता है।
कॉपियाँ Sent फ़ोल्डर में नहीं रखी जातीं, क्योंकि broadcast ही रिकॉर्ड है। GET /emails?broadcastId=brd_5a8c1e3f7b2d94a06c8e1f3b उन्हें सूचीबद्ध करता है, हर व्यक्ति के लिए एक।
इसे किसे मिलता है
कम से कम एक ऑडियंस का हर संपर्क, एक बार गिना जाता है चाहे कितनी भी ऑडियंस में हो। दो तरह के संपर्क छूट जाते हैं: वह जिसने हर उस चुनी हुई ऑडियंस की सदस्यता छोड़ दी है जिसमें वह है, और वह जिसका पता बाउंस या शिकायत के बाद, या किसी के जोड़ने से, रोक सूची में है। कॉल के बाद पर भेजना पहुँचने से पहले किसी ऑडियंस में जोड़े गए संपर्क को भी मिलता है।
भेजना ऑडियंस में एक बार में 50 लोगों से गुज़रता है और हर कॉपी उसी पाइपलाइन को देता है जिसे POST /emails इस्तेमाल करता है, इसलिए हर कॉपी किसी दूसरे संदेश की तरह दोबारा आज़माई, ट्रैक और रिपोर्ट की जाती है। POST /broadcasts/preview वह संख्या लौटाता है जिससे यह कॉल शुरू होगी, कुछ भेजे बिना।
कुछ भी लिखे जाने से पहले पूरे भेजे जाने की तुलना प्लान की मासिक भेजने की सीमा से की जाती है। जिस broadcast को कोटा पूरा नहीं कर सकता वह 429 send_quota_exceeded के साथ मना होता है और पीछे कुछ नहीं छोड़ता। हर कॉपी एक भेजना गिनी जाती है।
मर्ज फ़ील्ड
subject, html और text हर व्यक्ति के लिए भरे जाते हैं। हर फ़ील्ड बार के बाद एक फ़ॉलबैक लेता है, जो तब इस्तेमाल होता है जब संपर्क के पास उसका मान न हो, इसलिए बिना नाम सहेजे गए संपर्क के लिए {{firstName|there}} "there" बन जाता है। html में मान escape किए जाते हैं, ब्रेसेस के अंदर स्पेस की अनुमति है, और कोई भी दूसरा {{…}} ठीक वैसा ही छोड़ा जाता है जैसा लिखा है।
| फ़ील्ड | किससे भरा जाता है |
|---|---|
| `{{firstName}}` | संपर्क के नाम का पहला शब्द। |
| `{{lastName}}` | पहले शब्द के बाद संपर्क के नाम का बाकी हिस्सा। |
| `{{name}}` | संपर्क का पूरा नाम। |
| `{{email}}` | वह पता जिस पर कॉपी जा रही है। |
| `{{unsubscribeUrl}}` | वह लिंक जो इस व्यक्ति की इन ऑडियंस से सदस्यता छुड़ाता है। |
मुख्य भाग के बजाय template के साथ, वही पाँच मान props के रूप में दिए जाते हैं, पर सिर्फ़ वे props जिन्हें टेम्पलेट घोषित करता है। जो टेम्पलेट firstName घोषित करता है उसे वह मिलता है, और जो prop घोषित नहीं है वह कभी नहीं भेजा जाता, इसलिए कॉपियाँ किसी अनजान prop की वजह से कभी विफल नहीं होतीं। template.props में जो कुछ आप डालते हैं वह हर कॉपी में एक जैसा जाता है।
सदस्यता छोड़ना
हर कॉपी में List-Unsubscribe और List-Unsubscribe-Post: List-Unsubscribe=One-Click होते हैं। इसी से मेल क्लाइंट अपना सदस्यता छोड़ने का बटन दिखा पाता है, और बड़े मेलबॉक्स प्रदाता थोक मेल से यही माँगते हैं।
जो html या text मुख्य भाग ख़ुद {{unsubscribeUrl}} नहीं रखता, उसे एक पंक्ति का फ़ुटर मिलता है: "You are receiving this because you are on this mailing list. Unsubscribe"। टेम्पलेट ठीक वैसा ही भेजा जाता है जैसा है, इसलिए {{unsubscribeUrl}} टेम्पलेट में डालें।
लिंक Unsubscribe बटन वाला एक पेज खोलता है, इसलिए उसे लाने वाला लिंक स्कैनर किसी की सदस्यता नहीं छुड़ाता, जबकि मेल क्लाइंट का एक-क्लिक अनुरोध तुरंत सदस्यता छुड़ा देता है। दोनों तरह से व्यक्ति को हर उस ऑडियंस में सदस्यता छोड़ा हुआ चिह्नित किया जाता है जिसमें यह broadcast गया था, जो GET /audiences/{id}/contacts पर unsubscribedAt के रूप में दिखता है। उसकी दूसरी ऑडियंस, उसका संपर्क और उसे एक-एक करके भेजे गए मेल प्रभावित नहीं होते।
अस्वीकृतियाँ
| स्थिति | कोड | कब |
|---|---|---|
| 403 | from_address_forbidden | key from के रूप में नहीं भेज सकती। |
| 404 | audience_not_found | audienceIds में कोई id इस वर्कस्पेस की किसी ऑडियंस का नाम नहीं देता। |
| 409 | domain_not_sendable | from डोमेन अभी मेल पर हस्ताक्षर नहीं कर सकता, जैसा POST /emails पर होता है। |
| 422 | no_recipients | ऑडियंस खाली हैं, या उनमें सभी ने सदस्यता छोड़ दी है या रोके गए हैं। |
| 422 | invalid_parameter | कोई मुख्य भाग नहीं, template के साथ html या text, टेम्पलेट के बिना कोई subject नहीं, 10 से ज़्यादा ऑडियंस या 8 से ज़्यादा टैग, या ऐसा scheduledAt जो भविष्य में न हो या 365 दिन से ज़्यादा दूर हो। |
| 422 | template_not_found | टेम्पलेट हल नहीं होता। टेम्पलेट की दूसरी अस्वीकृतियाँ भी template.* का नाम देती हैं। |
| 422 | capability_unsupported | key खास पतों तक सीमित है। ऑडियंस पूरे वर्कस्पेस की होती हैं। |
| 429 | send_quota_exceeded | प्लान इस महीने सबके लिए एक कॉपी पूरी नहीं कर सकता। |
कोई अटैचमेंट, cc, bcc, अनुवाद या एन्क्रिप्शन नहीं। tags 8 तक लेता है, और हर कॉपी में broadcast_id भी होता है, जिसे सर्वर जोड़ता है।