الجماهير
`audiences.list` و`get` و`create` و`update` و`delete` و`empty` و`growth` و`list_contacts` و`add_contact` و`add_contacts` و`import_contacts` و`remove_contact` و`remove_contacts`.
كل الدوالّ
from openemail import openemail audiences = openemail.audiences.list_all()everyone = next((audience for audience in audiences if audience['builtin'] == 'default'), None) created = openemail.audiences.create({ 'name': 'Product updates', 'description': 'Customers who asked to hear about releases',})audience_id = created['id'] openemail.contacts.create({'email': '[email protected]', 'name': 'Grace Hopper'})openemail.audiences.add_contact(audience_id, {'email': '[email protected]'}) bulk = openemail.audiences.add_contacts(audience_id, { 'emails': ['[email protected]', '[email protected]'],}) imported = openemail.audiences.import_contacts(audience_id, { 'contacts': [{'email': '[email protected]', 'name': 'Katherine Johnson'}],}) members = openemail.audiences.list_all_contacts( audience_id, q='grace', sort='added-newest', limit=200,) growth = openemail.audiences.growth(audience_ids=[audience_id], days=30) openemail.audiences.update(audience_id, {'name': 'Release notes'})openemail.audiences.remove_contact(audience_id, '[email protected]')openemail.audiences.remove_contacts(audience_id, {'emails': ['[email protected]']})openemail.audiences.empty(audience_id)openemail.audiences.delete(audience_id) print(everyone['contactCount'] if everyone else None, bulk['missing'], imported['created'])print(len(members), growth['totals']['added'])الجمهور قائمة مسمّاة من جهات الاتصال في مساحة العمل هذه. وكل جهة اتصال تكون في الجمهور الافتراضي المدمج منذ لحظة وجودها، وbuiltin هو ما يسمّي ذلك الصف؛ وما عداه لك أن تنشئه وتملأه وتحذفه. فرّع على builtin لا على الاسم الذي يستطيع أي أحد تغييره.
أرسل إلى جمهور أو أكثر عبر openemail.broadcasts.send، في صفحة Broadcasts. وضع جهة اتصال في جمهور هو كتابة على الجمهور لا على جهة الاتصال، لذا فإن audiences:write هو النطاق الوحيد الذي يُتحقق منه. والاستثناء import_contacts: فهو ينشئ جهات اتصال، لذا يحتاج إلى contacts:write أيضًا.
يقبل add_contact عنواناً هو جهة اتصال أصلاً ويرفض ما ليس كذلك، بـ 422 contact_not_found. احفظه أولاً بـ openemail.contacts.create. وإضافة شخص مرتين تردّ بالعضوية القائمة أصلاً حاملةً addedAt الأصلي، فالطلب آمن لإعادة المحاولة.
يمكن إعادة تسمية الجمهور الافتراضي ووصفه كأي جمهور آخر، لكن لا يمكن حذفه ولا تقليمه. ويُرفض الأمران بـ 409 audience_immutable. احذف جهة الاتصال حين تقصد أن تذهب جهة الاتصال.
الاستجابة: AudienceResource
يُرجع list صفحة واحدة من هذه، قاموسًا فيه items وhasMore وnextCursor، الجمهور الافتراضي أولًا ثم البقية الأحدث أولًا، ويتصفّح list_all وiterate كل الصفحات. ويُرجع كل من get وcreate وupdate واحدًا منها. أما list_contacts فيُرجع صفحة من AudienceContactResource بدلًا من ذلك، أي جهات الاتصال نفسها مع تاريخ انضمام كل منها لا سجلات العضوية، وإلى جانبه list_all_contacts وiterate_contacts.
idstr- المقبض الدائم، `aud_` يليه 24 حرفاً ست عشرياً. الأسماء ليست فريدة، فهذا ما ينتمي إلى الإعدادات المخزَّنة.
namestr- يُقلَّم عند الكتابة، من 1 إلى 120 حرفاً. ويجوز أن يتشارك جمهوران اسماً واحداً، لأن الجمهور يُعنوَن بمعرّفه.
descriptionstr | None- نص حر لمن يقرأ القائمة لاحقًا. يكون `None` حين لا يكتبه أحد، وتمرير `None` صريح في `update` يمسحه.
builtinAudienceBuiltin | str | None- القيمة `default` على صف واحد بالضبط في كل مساحة عمل، وهو الجمهور الذي يحمل كل جهات الاتصال، و`None` على كل جمهور أنشأه شخص. ويبقى النوع مفتوحًا، مع `str` إلى جانب القيمة الحرفية، فلا يكسر جمهورٌ مدمج يُضاف لاحقًا الشيفرةَ المكتوبة وفق هذا النوع.
contactCountint- كم جهة اتصال في الجمهور، محسوبةً لحظة القراءة لا مأخوذة من ذاكرة مؤقتة. وقراءتان على جانبي `contacts.create` تختلفان بواحدة.
lastContactAtstr | None- بصيغة ISO-8601 بتوقيت UTC، وقت انضمام آخر جهة اتصال انضمت إلى هذا الجمهور. وتكون `None` ما دام الجمهور فارغًا.
createdAtstr- بصيغة ISO-8601 بتوقيت UTC، وقت إنشاء الجمهور. ويثبّت ترتيب القائمة بعد الجمهور الافتراضي.
updatedAtstr- بصيغة ISO-8601 بتوقيت UTC، يتحدّث عند إعادة التسمية أو تغيير الوصف. ولا تمسّه تغييرات العضوية.
المعاملات: audiences.list_contacts
limitint- كم جهة اتصال في الصفحة: عدد صحيح من 1 إلى 200، والقيمة الافتراضية 50.
cursorstr- قيمة `nextCursor` من الصفحة السابقة، تُرسل مع `q` و`source` و`sort` نفسها. والمؤشر الذي يشير إلى جهة اتصال ليست في هذا الجمهور يعطي 400 `invalid_cursor`.
qstr- يبحث في الاسم والعنوان، حتى 200 حرف. وإن لم يطابق شيء تمامًا في الصفحة الأولى، تُعاد تهجئات قريبة بدلًا من ذلك، وتواصل الصفحات التالية المطابقة بالطريقة نفسها.
sourceContactSource- `'manual'` لجهات الاتصال التي حفظها شخص ما عن قصد، و`'auto'` للتي سجّلها محرّر الرسائل في التطبيق. اتركه لكل مَن في الجمهور.
sortAudienceMemberSort- يتبع `'last-heard-newest'` (الافتراضي) و`'last-heard-oldest'` قيمة `lastSeenAt`، وتأتي جهات الاتصال التي لم تُراسَل قط في الآخر في الأول وفي البداية في الثاني. ويتبع `'added-newest'` و`'added-oldest'` وقت انضمام كل جهة اتصال إلى هذا الجمهور، ويتجاهل `'name'` حالة الأحرف ويرتّب جهة الاتصال التي بلا اسم بحسب عنوانها.
statusesSequence[AudienceMemberStatus]- `['subscribed']` يُبقي الأعضاء الذين لم يلغوا اشتراكهم و`['unsubscribed']` الذين ألغوه. اتركه فارغًا أو اذكر القيمتين لعرض كل من في الجمهور. تحتوي `AUDIENCE_MEMBER_STATUSES` على القيم.
الاستجابة: AudienceContactResource
يعيد list_contacts قيمة Page[AudienceContactResource]، ويمرّ list_all_contacts وiterate_contacts على كل الصفحات بالخيارات نفسها. وكل صف هو ContactResource، وحقوله موجودة في صفحة جهات الاتصال، مع حقلين إضافيين. والمرور على كل الصفحات هو طريقة تصدير الجمهور.
addedAtstr- بتوقيت UTC وفق ISO-8601، وقت انضمام جهة الاتصال إلى هذا الجمهور. وإخراج جهة الاتصال ثم إضافتها من جديد يبدأ القيمة من جديد.
unsubscribedAtstr | None- بصيغة ISO-8601 بتوقيت UTC، وقت إلغاء جهة الاتصال لاشتراكها من بث أُرسل إلى هذا الجمهور، أو `None` ما دامت مشتركة. وجهة الاتصال الملغية لاشتراكها تبقى في الجمهور، وتتخطاها عمليات البث إليه. وإخراجها ثم إضافتها من جديد يعيد اشتراكها.
الإضافة والإزالة دفعة واحدة
يأخذ add_contacts وremove_contacts القيمة {'emails': [...]}، من 1 إلى 200 عنوان، ويغيّران جمهورًا واحدًا بطلب واحد. ولا يُنشئ add_contacts جهة اتصال أبدًا: فالعنوان الذي ليس جهة اتصال يعود في missing، وimport_contacts هو الاستدعاء الذي يُنشئها. وكلاهما آمن للتكرار، لذا فإعادة المحاولة بعد انتهاء المهلة تبلّغ عن الأشخاص أنفسهم بأنهم أُنجزوا بدلًا من أن تفشل.
الإضافة إلى الجمهور الافتراضي تعيد 'added': 0، لأن كل جهة اتصال فيه أصلًا، ويُرفض remove_contacts عليه بـ 409 audience_immutable. وإخراج شخص من جمهور يُبقيه في دفتر العناوين وفي الجمهور الافتراضي وفي جماهيره الأخرى.
audienceIdstr- الجمهور الذي غيّره الاستدعاء، في النتيجتين كلتيهما.
addedint- في `AudienceBatchAddResource`: العضويات الجديدة التي أنشأها هذا الاستدعاء.
unchangedint- في `AudienceBatchAddResource`: جهات الاتصال التي كانت في الجمهور مسبقًا. ولم يُكتب لها شيء.
removedint- في `AudienceBatchRemoveResource`: العضويات التي أزالها هذا الاستدعاء.
notInAudiencelist[str]- في `AudienceBatchRemoveResource`: جهات الاتصال التي لم تكن في الجمهور، فلم يحدث لها شيء.
missinglist[str]- في كلتيهما: العناوين التي ليست جهات اتصال في مساحة العمل هذه، بأحرف صغيرة ومن دون تكرار.
الاستيراد
import_contacts هو استيراد CSV في صفحة الجمهور. يأخذ {'contacts': [...]}، من 1 إلى 500 صف، لكل منها email وname اختياري: كل عنوان سليم الصياغة يصبح جهة اتصال إن لم يكن كذلك بعد، وينتهي الجميع في الجمهور. أرسل القائمة الأطول على عدة استدعاءات. ويتطلب audiences:write وcontacts:write.
العنوان الذي هو جهة اتصال مسبقًا يُعاد استخدامه ويحتفظ باسمه، وname هنا لا يملأ إلا اسمًا فارغًا. وتُحفظ جهة الاتصال الجديدة بقيمة manual وتنضم أيضًا إلى الجمهور الافتراضي، والعنوان الذي حُذف من الدفتر يعود. وإعادة إرسال الصفوف نفسها لا تُنشئ شيئًا مرتين.
audienceIdstr- الجمهور الذي ذهبت إليه الصفوف.
createdint- جهات الاتصال الجديدة التي حفظها هذا الاستدعاء.
addedint- العضويات الجديدة في هذا الجمهور، بما فيها جهات الاتصال التي كانت موجودة ولم تكن فيه بعد.
skippedint- الصفوف التي لم تُستورد لأن العنوان كان غير سليم.
invalidlist[str]- العناوين غير السليمة، كما أُرسلت تمامًا.
الإفراغ
يُخرج empty(id) كل جهة اتصال من جمهور واحد بطلب واحد ويعيد EmptiedAudienceResource: الجمهور كما هو الآن، وcontactCount عند 0، مضافًا إليه removed، أي عدد العضويات المُزالة. ويحتفظ الجمهور بمعرّفه واسمه ووصفه، وتبقى كل جهة اتصال في دفتر العناوين وفي جماهيرها الأخرى.
لا يمكن التراجع عن ذلك، ولا شيء يسجّل مَن كان في القائمة، لذا مرّ على list_all_contacts أولًا إن كنت قد تريد استعادتها. ولا يمكن إفراغ الجمهور الافتراضي، ويُرفض الاستدعاء بـ 409 audience_immutable.
النمو
يقرأ growth() كم جهة اتصال انضمت إلى كل جمهور خلال فترة تنتهي الآن، باليوم أو الساعة أو الدقيقة، وهو المخطط في صفحة الجماهير. ويتطلب audiences:read ويعيد AudienceGrowthResource.
يسجّل الجمهور متى انضم شخص ما ولا يسجّل أبدًا متى غادر، لذا فكل رقم للانضمامات يعدّ الأشخاص الذين ما زالوا في القائمة اليوم بحسب تاريخ انضمامهم، ولا ينخفض أي خط أبدًا. وجهة الاتصال التي انضمت ثم غادرت لا تدخل في أي من الأرقام.
المعاملات
audience_idsSequence[str]- حتى 50 معرّف جمهور، تُرسل مفصولة بفواصل. اتركه لكل الجماهير. والمعرّف الذي ليس جمهورًا في مساحة العمل هذه يعطي 404 `audience_not_found`.
daysint- إلى أي مدى تمتد الفترة إلى الوراء، من 1 إلى 1095. وهي 30 حين لا يُعطى `days` ولا `minutes`.
minutesint- الفترة بالدقائق، من 1 إلى 1576800، لفترة أقصر من يوم. وتكون لها الأولوية على `days` حين يُعطى الاثنان.
grainTrackingGrain- حجم كل فترة فرعية: `day` (الافتراضي) أو `hour` أو `minute`.
offset_minutesint- فرق توقيت المشاهد عن UTC بالدقائق، من -840 إلى 840، لتبدأ فترات اليوم والساعة عند حدوده المحلية. والقيمة الافتراضية 0.
الاستجابة
sincestr- بتوقيت UTC وفق ISO-8601، بداية أول فترة فرعية.
untilstr- بتوقيت UTC وفق ISO-8601، لحظة القراءة.
totalsAudienceGrowthTotals- `contacts` يعدّ كل شخص مرة واحدة مهما كان عدد القوائم التي هو فيها، و`memberships` يجمع القوائم، فيُعدّ الشخص مرة عن كل قائمة مقروءة تضمه. و`subscribed` يعدّ، مرة واحدة لكل منهم، الأشخاص الذين ما زالوا مشتركين في قائمة واحدة على الأقل من القوائم المقروءة. و`added` يجمع الانضمامات في الفترة، و`unsubscribed` إلغاءات الاشتراك فيها، و`lists` عدد الجماهير التي قُرئت، و`busiest` الفترة التي شهدت أكبر عدد من الانضمامات، أو `None`.
serieslist[AudienceGrowthSeries]- إدخال واحد لكل جمهور، من الأكبر: `id` و`name` و`builtin` (قيمته `True` في الجمهور الافتراضي) و`total` الأعضاء الآن و`subscribed` (مَن لم يُلغوا اشتراكهم منهم) و`before` (مَن انضموا قبل `since`) و`added` (مَن انضموا داخل الفترة) و`unsubscribed` (مَن ألغوا اشتراكهم داخلها) و`buckets`، وكل منها قاموس فيه `bucket` و`added` و`unsubscribed`. ولا تُسرد إلا الفترات التي فيها انضمام أو إلغاء اشتراك، بمفاتيح `YYYY-MM-DD` أو `YYYY-MM-DDTHH` أو `YYYY-MM-DDTHH:MM` بالتوقيت المحلي لفرق التوقيت.
المرجع
audiences.list()المرجع الكاملaudiences.list_all()المرجع الكاملaudiences.iterate()المرجع الكاملaudiences.get()المرجع الكاملaudiences.create()المرجع الكاملaudiences.update()المرجع الكاملaudiences.delete()المرجع الكاملaudiences.empty()المرجع الكاملaudiences.growth()المرجع الكاملaudiences.list_contacts()المرجع الكاملaudiences.list_all_contacts()المرجع الكاملaudiences.iterate_contacts()المرجع الكاملaudiences.add_contact()المرجع الكاملaudiences.add_contacts()المرجع الكاملaudiences.import_contacts()المرجع الكاملaudiences.remove_contact()المرجع الكاملaudiences.remove_contacts()المرجع الكامل