الإرسال إلى الجماهير

يرسل رسالة واحدة إلى كل من في جمهور أو أكثر، بنسخة منفصلة لكل شخص مخصصة من جهة اتصاله. لكل نسخة مستلم واحد بالضبط بلا cc ولا bcc، فلا يرى أحد لمن ذهبت أيضًا، وكل نسخة رسالة عادية لها معرّف msg_ وأحداث وتتبع وخطافات ويب خاصة بها. يجيب الاستدعاء بـ 202 فورًا ويستمر الإرسال في الخلفية، فتابعه عبر GET /broadcasts/{id}.

يحتاج إلى emails:send وaudiences:read. يضم audienceIds من 1 إلى 10 معرّفات. يأتي المتن من 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}

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

يمر الإرسال على الجماهير 50 شخصًا في كل مرة ويسلّم كل نسخة إلى المسار نفسه الذي يستخدمه POST /emails، فتُعاد محاولة كل نسخة وتُتتبع ويُبلَّغ عنها كأي رسالة أخرى. ويعيد POST /broadcasts/preview العدد الذي سيبدأ منه هذا الاستدعاء، دون إرسال أي شيء.

تُملأ subject وhtml وtext لكل شخص. ويقبل كل حقل قيمة بديلة بعد شرطة تُستخدم حين لا تكون لجهة الاتصال قيمة له، فيصير {{firstName|there}} "there" لجهة اتصال محفوظة بلا اسم. تُهرَّب القيم في html، وتُسمح المسافات داخل الأقواس، ويُترك أي {{…}} آخر كما كُتب تمامًا.

مع template بدلًا من متن، تُمرَّر القيم الخمس نفسها كخصائص، لكن فقط الخصائص التي يعلنها القالب. فالقالب الذي يعلن firstName يحصل عليها، والخاصية التي لا يعلنها لا تُرسل أبدًا، فلا تفشل النسخ أبدًا بسبب خاصية مجهولة. وكل ما تضعه في 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}} في القالب.

يفتح الرابط صفحة فيها زر إلغاء الاشتراك، فماسح الروابط الذي يجلبه لا يلغي اشتراك أحد، بينما طلب النقرة الواحدة الذي يرسله برنامج البريد يلغي الاشتراك فورًا. وفي الحالتين يُعلَّم الشخص كملغٍ للاشتراك في كل جمهور ذهب إليه هذا البث، ويظهر ذلك كـ unsubscribedAt في GET /audiences/{id}/contacts. ولا تتأثر جماهيره الأخرى ولا جهة اتصاله ولا البريد المرسل إليه رسالةً رسالة.