البث

import time from openemail import openemailfrom openemail.types import BroadcastCreate draft: BroadcastCreate = {    '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'},} reach = openemail.broadcasts.preview(draft)print(reach['recipients'], reach['unsubscribed'], reach['suppressed']) broadcast = openemail.broadcasts.send(draft) latest = openemail.broadcasts.get(broadcast['id'])while latest['status'] in ('scheduled', 'queued', 'sending'):    time.sleep(5)    latest = openemail.broadcasts.get(broadcast['id']) for copy in openemail.broadcasts.iterate_recipients(broadcast['id']):    print(copy['email'], copy['status'], copy['opens'], copy['clicks']) bounced = openemail.broadcasts.list_recipients(broadcast['id'], filter='bounced')if bounced['items']:    content = openemail.broadcasts.get_recipient(broadcast['id'], bounced['items'][0]['emailId'])    print(content['subject'], content['bouncedAt']) stats = openemail.broadcasts.stats(broadcast['id'], grain='day')print(stats['totals']['opened'], stats['totals']['clicked'], stats['totals']['unsubscribed']) lately = openemail.broadcasts.stats(broadcast['id'], days=1)print(lately['window']['opened'] if lately['window'] else None) month = openemail.broadcasts.analytics(days=30)for row in month['broadcasts']:    print(row['subject'], row['sent'], row['opened']) later = openemail.broadcasts.send({**draft, 'scheduledAt': 'P1D'})openemail.broadcasts.cancel(later['id']) history = openemail.broadcasts.list(audience_id=draft['audienceIds'][0])print(latest['status'], latest['counts']['sent'], len(history['items']))

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

يعود send فورًا مع البث في حالة queued، أو scheduled حين تمرر scheduledAt، ويستمر الإرسال في الخلفية. يحتاج send إلى emails:send وaudiences:read، ويحتاج preview إلى audiences:read، وتحتاج list وlist_all وiterate وget وlist_recipients وlist_all_recipients وiterate_recipients وget_recipient وstats وanalytics إلى 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.list_contacts. ويبقى في الجمهور وفي دفتر العناوين، ولا تُمس جماهيره الأخرى، ويظل البريد المرسل إليه رسالةً رسالة يخرج. وإخراجه من الجمهور ثم إضافته من جديد يعيد اشتراكه.

يصل البث إلى كل جهة اتصال في واحد على الأقل من 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، وإلغاء بث مُلغى يعيده كما هو.

يعيد list_recipients صفحة واحدة من الأشخاص الذين ذهب إليهم البث، صف لكل نسخة، مرتبة حسب العنوان، في صورة قاموس فيه items وhasMore وnextCursor. ويمر list_all_recipients على كل الصفحات في قائمة واحدة، ويُنتج iterate_recipients نسخة واحدة في كل مرة، ولا يجلب الصفحة التالية إلا حين تطلبها الحلقة. وتتراوح limit من 1 إلى 200 وقيمتها الافتراضية 50، ويُعاد cursor مع filter وq نفسيهما.

تسمّي BROADCAST_RECIPIENT_FILTERS كل مرشّح، ويبحث q في العنوان والاسم دون تمييز لحالة الأحرف. تستبعد الفتحات والنقرات وكلاء الصور وماسحات الروابط، وتبقى 0 حين يخرج البث والتتبع معطّل.

يعيد get_recipient(id, email_id) نسخة واحدة: الصف نفسه، إضافة إلى subject وhtml وtext كما تلقّاها ذلك الشخص تمامًا، مع ملء حقول الدمج ورابط إلغاء الاشتراك الخاص به. وHTML من قبل إضافة تتبع الفتح والنقر. وقيمة email_id ليست نسخة من هذا البث ترفع 404 recipient_not_found، والبث غير المعروف يرفع 404 broadcast_not_found.

يعيد stats المجاميع وسلسلة. تعدّ totals النسخ sent وdelivered وbounced وcomplained وfailed، مع pending للنسخ التي ما زالت تنتظر، والأشخاص الذين opened وclicked وunsubscribed، مع opens وclicks كأعداد للأحداث. وseries متفرقة والأقدم أولًا، فترة واحدة لكل grain (minute أو hour أو day، والافتراضي hour) حدث فيها شيء، مقسّمة بـ offset_minutes شرق UTC. وهي تعدّ كل شخص مرة واحدة، عند أول مرة حدث له ذلك، فيتطابق مجموعها مع المجاميع.

يعيد كل من get وcancel واحدًا من هذه، ويعيد send قيمة SentBroadcastResource، وهي الحقول نفسها مضافًا إليها replayed، التي تكون True حين يكون الجواب هو البث الذي أنشأه استدعاء سابق بمفتاح اللاتكرارية نفسه. ويعيد list صفحة منها، قاموسًا فيه items وhasMore وnextCursor، الأحدث أولًا، ويمر list_all وiterate على كل الصفحات. ويعيد preview قيمة BroadcastPreviewResource فيها audienceIds وrecipients وunsubscribed وsuppressed. ويعيد list_recipients صفحة من صفوف BroadcastRecipientResource، وget_recipient قيمة BroadcastRecipientContentResource، وstats قيمة BroadcastStatsResource.

كل صف من list_recipients وlist_all_recipients وiterate_recipients. ويضيف BroadcastRecipientContentResource، من get_recipient، الحقول subject وhtml وtext.

• broadcasts.preview()المرجع الكامل
• broadcasts.send()المرجع الكامل
• broadcasts.list()المرجع الكامل
• broadcasts.list_all()المرجع الكامل
• broadcasts.iterate()المرجع الكامل
• broadcasts.get()المرجع الكامل
• broadcasts.list_recipients()المرجع الكامل
• broadcasts.list_all_recipients()المرجع الكامل
• broadcasts.iterate_recipients()المرجع الكامل
• broadcasts.get_recipient()المرجع الكامل
• broadcasts.stats()المرجع الكامل
• broadcasts.analytics()المرجع الكامل
• broadcasts.cancel()المرجع الكامل