संपर्क, ऑडियंस और ब्रॉडकास्ट

जिन लोगों को आप लिखते हैं, उन्हें चार नेमस्पेस कवर करते हैं। संपर्क वर्कस्पेस की पता पुस्तिका हैं, ऑडियंस संपर्कों की नाम वाली सूचियाँ हैं, ब्रॉडकास्ट कुछ ऑडियंस में मौजूद हर व्यक्ति को एक संदेश भेजता है, और सप्रेशन सूची में वे पते होते हैं जिन पर वर्कस्पेस नहीं भेजेगा। हर कमांड एक SDK मेथड कॉल करती है, इसलिए SDK पेज उन्हीं कॉल को ज़्यादा विस्तार से बताते हैं।

• —संपर्क की कोई ID नहीं होती। उसका पता ही वह कुंजी है जो हर contacts कमांड लेती है, आगे-पीछे की ख़ाली जगह हटाकर और छोटे अक्षरों में, इसलिए [email protected] और [email protected] एक ही संपर्क हैं। ऑडियंस की aud_ ID होती है, ब्रॉडकास्ट की brd_ ID, और सप्रेशन की वह ID जो suppressions list प्रिंट करती है।
• —हर संपर्क जब तक मौजूद है, डिफ़ॉल्ट ऑडियंस में रहता है। उस ऑडियंस को न हटाया जा सकता है, न ख़ाली किया जा सकता है, न उसमें से किसी को निकाला जा सकता है, और उस पर builtin default होता है।
• —पता पुस्तिका वर्कस्पेस की होती है, इसलिए हर सदस्य और हर कुंजी उसी एक को पढ़ती और लिखती है।
• —हर नेमस्पेस अपने एकवचन रूप से भी चलता है, जैसे openemail contact get, और सामान्य उपनाम काम करते हैं: ls, show, new, edit और rm। suppressions में, जिसके वर्ब add और remove हैं, new से add चलता है और rm से remove।

वर्कस्पेस की पता पुस्तिका: वे लोग जिन्हें किसी सदस्य ने ऐप के कंपोज़र से लिखा है, और हाथ से सहेजा गया हर कोई। आने वाली मेल किसी को नहीं जोड़ती, और न ही API या CLI से भेजना।

संपर्कों की नाम वाली सूचियाँ, एक वर्कस्पेस में 100 तक। किसी पते को ऑडियंस में जुड़ने से पहले संपर्क होना चाहिए, सिवाय import-contacts के, जो साथ-साथ नए पते सहेजती जाती है।

10 तक ऑडियंस में मौजूद हर व्यक्ति को एक संदेश, हर व्यक्ति के लिए अलग कॉपी के रूप में भेजा गया, मर्ज फ़ील्ड भरे हुए और सदस्यता छोड़ने के लिंक के साथ। हर कॉपी एक सामान्य ईमेल है, अपनी msg_ ID, इवेंट और वेबहुक के साथ।

वे पते जिन पर यह वर्कस्पेस नहीं भेजेगा: हार्ड बाउंस और शिकायतें, जो होते ही दर्ज होती हैं, और हाथ से जोड़ा गया हर पता। इनमें से किसी को भेजना, कुछ भी निकलने से पहले, उस प्राप्तकर्ता के लिए अस्वीकार हो जाता है।

ज़्यादातर कमांड को अपने नेमस्पेस का पढ़ने या लिखने का स्कोप चाहिए। कुछ को कोई दूसरा चाहिए, क्योंकि वे कुछ और पढ़ती या बदलती हैं:

• —किसी ख़ास पते या डोमेन तक सीमित कुंजी भी वही पता पुस्तिका पढ़ती और लिखती है जो हर दूसरी कुंजी। वह सिर्फ़ उन्हीं ब्रॉडकास्ट को देखती है जो उसके पास मौजूद किसी पते या डोमेन से भेजे गए, list-people से सिर्फ़ सहेजे गए संपर्क पाती है, और contacts list-threads, activity, block और unblock, और suppressions add और remove उसे 422 capability_unsupported के साथ अस्वीकार करते हैं।
• —जिस सदस्य की पहुँच सिर्फ़ कुछ पतों तक है, उसका ब्राउज़र साइन-इन हर contacts, audiences और broadcasts कमांड पर 422 capability_unsupported के साथ अस्वीकार होता है। suppressions add वर्कस्पेस के मालिक के अलावा किसी का भी ब्राउज़र साइन-इन अस्वीकार करता है।

फ़ाइल से ऑडियंस बनाएँ, फिर गिनें कि उसे ब्रॉडकास्ट किन तक पहुँचेगा। import-contacts उन पतों को सहेजती है जो अभी संपर्क नहीं हैं, और दोबारा चलाने पर कुछ भी दो बार नहीं बनता या जुड़ता।

[  { "email": "[email protected]", "name": "Ada Lovelace" },  { "email": "[email protected]", "name": "Grace Hopper" },  { "email": "[email protected]" }]

AUDIENCE=$(openemail audiences create --name 'Product updates' --json | jq -r .id)openemail audiences import-contacts "$AUDIENCE" --contacts @contacts.jsonopenemail broadcasts preview --audience-ids "$AUDIENCE"

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

{  "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>",  "scheduledAt": "2026-10-01T09:00:00Z"}

openemail broadcasts send --data @broadcast.json --dry-runBROADCAST=$(openemail broadcasts send --data @broadcast.json --yes --json | jq -r .id)openemail broadcasts get "$BROADCAST"openemail broadcasts stats "$BROADCAST" --grain day

देखें कि ब्रॉडकास्ट किन तक नहीं पहुँचा। --ndjson हर लाइन में एक प्राप्तकर्ता प्रिंट करता है, और --all --json हर पेज वाला एक दस्तावेज़।

openemail broadcasts list-recipients brd_5a8c1e3f7b2d94a06c8e1f3b --filter bounced --ndjson | jq -r .emailopenemail broadcasts list-recipients brd_5a8c1e3f7b2d94a06c8e1f3b --filter not_opened --all --json | jq ".items | length"openemail suppressions list --reason bounce --all --max 50

एक ऑडियंस के सब्सक्राइब सदस्यों को दूसरी में कॉपी करें। jq स्ट्रीम को उस बॉडी में बदलता है जो add-contacts लेती है, और --data - उसे stdin से पढ़ता है। --max 200 इसे उन 200 पतों तक रखता है जो एक कॉल स्वीकार करती है।

openemail audiences list-contacts aud_9f2c4b7e1a0d63d84c5f2e7b --statuses subscribed --max 200 --ndjson \  | jq -s '{ emails: map(.email) }' \  | openemail audiences add-contacts aud_1c4e7a9b2d0f36e85a7c1b4d --data -

किसी एक डोमेन पर कंपोज़र के दर्ज किए हर संपर्क को हटाएँ। delete-many एक कॉल में 200 तक पते लेती है, इसलिए xargs -n 200 लंबी सूची को बाँटता है। पहले --dry-run से बैच जाँच लें, क्योंकि इसे पूर्ववत नहीं किया जा सकता।

openemail contacts list --source auto --all --ndjson \  | jq -r 'select(.email | endswith("@old-vendor.example")) | .email' > leaving.txtxargs -n 200 openemail contacts delete-many --dry-run < leaving.txtxargs -n 200 openemail contacts delete-many --yes < leaving.txt

किसी पते पर भेजना बंद करें, किसी को फिर अनुमति दें, और एक भेजने वाले को ब्लॉक करें। removable बताता है कि suppressions remove कौन-सी पंक्तियाँ लेगी।

openemail suppressions add --email [email protected]openemail suppressions list --q [email protected] --json | jq -r '.items[] | select(.removable) | .id'openemail suppressions remove 7b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e --yesopenemail contacts block [email protected]

ये कमांड चलने से पहले टर्मिनल में पुष्टि माँगती हैं:

• —--yes आपकी ओर से पुष्टि करता है। बिना निगरानी के, --json या --no-input के साथ, CI में या बिना टर्मिनल के, जो कमांड पूछती वह Refusing to run unattended. Pass --yes to confirm. और एग्ज़िट कोड 2 के साथ रुकती है।
• —--dry-run वह अनुरोध प्रिंट करता है जो कमांड भेजती, और बिना पूछे और बिना कुछ बदले कोड 0 के साथ बाहर निकलता है।
• —ब्राउज़र साइन-इन के साथ, audiences delete पहले सत्यापन कोड माँगती है, जैसे वेब ऐप करता है। --yes इसे कभी नहीं छोड़ता, और बिना निगरानी के कमांड एग्ज़िट कोड 4 के साथ रुकती है। पहले openemail verify चलाएँ, या API कुंजी इस्तेमाल करें, जिससे कभी नहीं पूछा जाता।
• —audiences empty कभी सत्यापन कोड नहीं माँगती, इसलिए --yes देने से पहले ID जाँच लें।

सूची देने वाली हर कमांड एक पेज पढ़ती है। जब और बाकी हों, तो प्रिंट किया गया कर्सर उन्हीं फ़िल्टर के साथ --cursor को दें, या सब पढ़ें:

• —--all हर पेज पढ़ता है और आइटम स्ट्रीम करता है: टर्मिनल पर एक टेबल, और पाइप करने पर या --ndjson के साथ हर लाइन में एक JSON ऑब्जेक्ट।
• —--max <n> उतने आइटम के बाद रुकता है, और इसमें --all अपने आप शामिल है।
• —--json एक ही { items, hasMore, nextCursor } दस्तावेज़ प्रिंट करता है, --all के साथ भी।
• —ग़लत या पुराना कर्सर 400 invalid_cursor देता है। बिना कर्सर के फिर से शुरू करें।

• —contacts create पता पुस्तिका में पहले से मौजूद पते को 409 contact_exists के साथ अस्वीकार करती है, इसलिए दोबारा कोशिश कभी किसी के बदले नाम को नहीं मिटाती। contacts save कभी अस्वीकार नहीं करती: पता किसी भी स्थिति में हो, यह उसे सहेजती, रखती या वापस लाती है।
• —contacts delete ऐसा पता भी लेती है जो सिर्फ़ मेल में दिखा था, जिससे वह व्यक्ति list-people से हट जाता है। मेल बनी रहती है। इसे पूर्ववत नहीं किया जा सकता: पता फिर से सहेजने पर संपर्क बिना नाम, बिना नोट्स और डिफ़ॉल्ट के अलावा बिना किसी ऑडियंस के शुरू होता है।
• —पता ही संपर्क की पहचान है, इसलिए contacts update उसे नहीं बदल सकती। संपर्क को दूसरे पते पर ले जाना एक delete और एक create है।
• —contacts set-photo इमेज फ़ाइल से, या - से stdin से पढ़ती है। --content-type दें, जैसे image/jpeg: इसके बिना इमेज application/octet-stream के रूप में जा सकती है, जिसे सर्वर 422 invalid_image के साथ अस्वीकार करता है।
• —broadcasts send --scheduled-at 2026-10-01T09:00:00Z जैसा ISO 8601 समय, या PT2H या P1D जैसी ISO 8601 अवधि लेता है, 365 दिन आगे तक। send --at जो छोटी देरी लेता है, जैसे 2h, वह यहाँ अस्वीकार होती है।
• —मर्ज फ़ील्ड --subject, --html और --text में काम करते हैं: {{firstName}}, {{lastName}}, {{name}}, {{email}} और {{unsubscribeUrl}}, हर एक खड़ी लकीर के बाद एक फ़ॉलबैक मान के साथ, जैसे {{firstName|there}}। जिस बॉडी में {{unsubscribeUrl}} नहीं रखा गया, उसे एक लाइन का सदस्यता छोड़ने वाला फ़ुटर मिलता है। टेम्पलेट जैसा है वैसा भेजा जाता है, इसलिए लिंक टेम्पलेट में डालें।
• —कुछ भी लिखे जाने से पहले ब्रॉडकास्ट को प्लान की मासिक भेजने की सीमा से जाँचा जाता है, और हर कॉपी एक भेजना गिनी जाती है। जिसे कोटा पूरा न कर सके वह 429 send_quota_exceeded के साथ अस्वीकार होता है, और पीछे कुछ नहीं छूटता।
• —जब कोई स्क्रिप्ट यह चरण दोबारा चला सकती हो, तो broadcasts send को अपनी --idempotency-key दें। वही कुंजी नया भेजने के बजाय वह ब्रॉडकास्ट लौटाती है जो उसने बनाया था।
• —ब्रॉडकास्ट से सदस्यता छोड़ने वाला संपर्क unsubscribedAt सेट होकर ऑडियंस में बना रहता है, और उस ऑडियंस को बाद के ब्रॉडकास्ट उसे छोड़ देते हैं। audiences list-contacts --statuses unsubscribed उनकी सूची देती है।
• —हार्ड बाउंस सप्रेशन सूची में बना रहता है। suppressions remove उसे 409 suppression_not_removable के साथ अस्वीकार करती है, और हर पंक्ति का removable यह पहले से बता देता है।