جهات الاتصال والجماهير والبث

أربع مساحات أسماء تغطي الأشخاص الذين تكتب إليهم. جهات الاتصال هي دفتر عناوين مساحة العمل، والجماهير قوائم مسمّاة من جهات الاتصال، والبث يرسل رسالة واحدة إلى كل من في بعض الجماهير، وقائمة المنع تضم العناوين التي لن ترسل إليها مساحة العمل. كل أمر يستدعي طريقة واحدة من SDK، لذا تصف صفحات SDK الاستدعاءات نفسها بعمق أكبر.

• —جهة الاتصال بلا معرّف. عنوانها هو المفتاح الذي يأخذه كل أمر contacts، بعد تقليم المسافات وتحويله إلى أحرف صغيرة، فـ [email protected] و[email protected] جهة اتصال واحدة. وللجمهور معرّف aud_، وللبث معرّف brd_، وللمنع المعرّف الذي يطبعه 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_ خاص به وأحداثه وخطافات الويب الخاصة به.

العناوين التي لن ترسل إليها مساحة العمل هذه: الارتدادات الصلبة والشكاوى، مسجلة لحظة حدوثها، وأي عنوان تضيفه يدويًا. والإرسال إلى أحدها يُرفض لذلك المستلم قبل أن يخرج أي شيء.

تحتاج معظم الأوامر إلى نطاق القراءة أو الكتابة لمساحة أسمائها. وبعضها يحتاج إلى نطاق آخر، لأنه يقرأ شيئًا آخر أو يغيّره:

• —المفتاح المقيّد بعناوين أو نطاقات معيّنة يقرأ دفتر العناوين نفسه الذي يقرؤه كل مفتاح آخر ويكتب فيه. لا يرى إلا البث المرسل من عنوان أو نطاق يحمله، ولا يحصل من list-people إلا على جهات الاتصال المحفوظة، ويُرفض بـ 422 capability_unsupported في contacts list-threads وactivity وblock وunblock، وفي suppressions add وremove.
• —تسجيل الدخول عبر المتصفح لعضو لا يصل إلا إلى بعض العناوين يُرفض بـ 422 capability_unsupported في كل أمر contacts وaudiences وbroadcasts. ويرفض 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.

كل أمر يسرد يقرأ صفحة واحدة. وحين يبقى المزيد، مرّر المؤشر الذي طبعه إلى --cursor، مع المرشّحات نفسها، أو اقرأها كلها:

• —يقرأ --all كل صفحة ويبث العناصر: جدولًا في الطرفية، وكائن JSON واحدًا في كل سطر عند التمرير عبر أنبوب أو مع --ndjson.
• —يتوقف --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 وقتًا بصيغة ISO 8601 مثل 2026-10-01T09:00:00Z، أو مدة بصيغة ISO 8601 مثل PT2H أو P1D، حتى 365 يومًا من الآن. والمهل القصيرة التي يأخذها send --at، مثل 2h، تُرفض هنا.
• —تعمل حقول الدمج في --subject و--html و--text: {{firstName}} و{{lastName}} و{{name}} و{{email}} و{{unsubscribeUrl}}، ولكل منها قيمة احتياطية بعد خط عمودي، كما في {{firstName|there}}. والجسم الذي لا يضع {{unsubscribeUrl}} يحصل على تذييل من سطر واحد لإلغاء الاشتراك. أما القالب فيُرسل كما هو، لذا ضع الرابط في القالب.
• —يُفحص البث مقابل عمليات الإرسال الشهرية للخطة قبل كتابة أي شيء، وكل نسخة تُحتسب إرسالًا واحدًا. والبث الذي لا تكفيه الحصة يُرفض بـ 429 send_quota_exceeded، ولا يبقى منه شيء.
• —مرّر --idempotency-key خاصًا بك إلى broadcasts send حين قد يعيد سكربت تشغيل الخطوة. والمفتاح نفسه يجيب بالبث الذي أنشأه بدلًا من إرسال بث جديد.
• —جهة الاتصال التي تلغي اشتراكها من بث تبقى في الجمهور مع ضبط unsubscribedAt، ويتخطاها البث اللاحق إلى ذلك الجمهور. ويسردها audiences list-contacts --statuses unsubscribed.
• —يبقى الارتداد الصلب في قائمة المنع. يرفضه suppressions remove بـ 409 suppression_not_removable، وتقول removable في كل صف ذلك مسبقًا.