البث

const 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' },} const reach = await openemail.broadcasts.preview(draft)console.log(reach.recipients, reach.unsubscribed, reach.suppressed) const broadcast = await openemail.broadcasts.send(draft) let latest = await openemail.broadcasts.get(broadcast.id)while (['scheduled', 'queued', 'sending'].includes(latest.status)) {  await new Promise((resolve) => setTimeout(resolve, 5_000))  latest = await openemail.broadcasts.get(broadcast.id)} for await (const copy of openemail.emails.iterate({ broadcastId: broadcast.id })) {  console.log(copy.id, copy.status)} const later = await openemail.broadcasts.send({ ...draft, scheduledAt: 'P1D' })await openemail.broadcasts.cancel(later.id) const history = await openemail.broadcasts.list({ audienceId: draft.audienceIds[0] })console.log(latest.status, latest.counts.sent, history.items.length)

البث يرسل رسالة واحدة إلى كل من في جمهور أو أكثر، بنسخة منفصلة لكل شخص. لكل نسخة مستلم واحد بالضبط بلا cc ولا bcc، فلا يرى أحد لمن ذهبت أيضًا، وكل نسخة رسالة عادية لها معرّف msg_ وأحداث وتتبع وخطافات ويب خاصة بها. ويعرضها emails.list({ broadcastId }). ولا تُحفظ النسخ في مجلد المرسل، لأن البث هو السجل.

يُحَل send فورًا مع البث في حالة queued، أو scheduled حين تمرر scheduledAt، ويستمر الإرسال في الخلفية. يحتاج send إلى emails:send وaudiences:read، ويحتاج preview إلى audiences:read، وتحتاج list وlistAll وiterate وget إلى emails:read، ويحتاج cancel إلى emails:send.

تُملأ subject وhtml وtext لكل شخص من جهة اتصاله. {{firstName}} هي الكلمة الأولى من اسم جهة الاتصال، و{{lastName}} بقيته، و{{name}} الاسم كاملًا، و{{email}} العنوان الذي تذهب إليه النسخة، و{{unsubscribeUrl}} الرابط الذي يلغي اشتراكه.

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

مرّر template بدلًا من html وtext لإرسال قالب محفوظ. تصل إليه القيم الخمس نفسها كخصائص، لكن فقط الخصائص التي يعلنها القالب، فالقالب الذي يعلن firstName يحصل عليها والذي لا يعلنها لا يُرفض بسببها أبدًا. وكل ما في template.props يذهب إلى كل النسخ على حد سواء.

تحمل كل نسخة ترويسات إلغاء الاشتراك بنقرة واحدة التي تتيح لبرنامج البريد عرض زر إلغاء الاشتراك الخاص به، وهو ما يطلبه كبار مزودي صناديق البريد من البريد الجماعي. والمتن html أو text الذي لا يضع {{unsubscribeUrl}} بنفسه يحصل على تذييل من سطر واحد فيه الرابط. أما القالب فيُرسل كما هو تمامًا، فضع {{unsubscribeUrl}} في القالب.

إلغاء الاشتراك يعلّم الشخص كملغٍ للاشتراك في كل جمهور ذهب إليه ذلك البث، ويُظهر ذلك AudienceContactResource.unsubscribedAt في audiences.listContacts. ويبقى في الجمهور وفي دفتر العناوين، ولا تُمس جماهيره الأخرى، ويظل البريد المرسل إليه رسالةً رسالة يخرج. وإخراجه من الجمهور ثم إضافته من جديد يعيد اشتراكه.

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

يعيد preview الأعداد نفسها دون إرسال: recipients وunsubscribed وsuppressed. وsend الذي لن يصل إلى أحد يرمي 422 no_recipients.

يقرأ get قيم counts مباشرة من النسخ، فاستطلعه أثناء إرسال البث. تنتقل status من scheduled أو queued إلى sending وتستقر على sent حين تخرج كل نسخة سُلّمت أو تفشل. وتبقى sending ما دامت نسخ تنتظر، حتى بعد أن يقول completedAt إن آخر شخص قد وُصل إليه. وfailed تعني أن البث كله توقف، ويقول lastError السبب: لم يعد ممكنًا الإرسال من عنوان from، أو توقف القالب عن الحل، أو نفدت الخطة في منتصف الطريق، أو ظل الإرسال نفسه يفشل، أو تعذرت كتابة أي نسخة.

يوقف cancel بثًا حالته scheduled أو queued أو sending. لا يُضاف أحد آخر وتُلغى كل نسخة ما زالت تنتظر، بينما النسخ التي خرجت لا يمكن استرجاعها. وبمجرد أن تخرج كل النسخ يرمي cancel الخطأ 409 broadcast_not_cancellable، وإلغاء بث مُلغى يُحَل به كما هو.

يُحَل كل من send وget وcancel بواحد من هذه. ويُحَل list بصفحة منها، { items, hasMore, nextCursor }، الأحدث أولًا، ويمر listAll وiterate على كل الصفحات. ويُحَل preview بـ BroadcastPreviewResource فيه audienceIds وrecipients وunsubscribed وsuppressed.