گروه‌های مخاطب
`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'])یک audience فهرستی نام‌دار از مخاطبان این فضای کاری است. هر مخاطب از همان لحظهٔ ساخته‌شدنش در audience پیش‌فرض درون‌ساخت است، و builtin همان چیزی است که آن ردیف را نام می‌برد؛ بقیه را خودتان می‌سازید، پر می‌کنید و حذف می‌کنید. به‌جای نام که هرکسی می‌تواند عوضش کند، روی builtin شاخه بزنید.
با openemail.broadcasts.send برای یک یا چند گروه مخاطب بفرستید، در صفحهٔ Broadcasts. گذاشتن مخاطب در گروه نوشتن روی گروه است نه روی مخاطب، پس audiences:write تنها دامنهٔ دسترسی است که بررسی می‌شود. import_contacts استثناست: مخاطب می‌سازد، پس contacts:write هم لازم دارد.
add_contact آدرسی را می‌گیرد که از پیش مخاطب است و آدرسی را که نیست با 422 contact_not_found رد می‌کند. نخست آن را با openemail.contacts.create ذخیره کنید. افزودن دوبارهٔ یک نفر با همان عضویتی که از پیش هست پاسخ می‌دهد و addedAt اصلی خود را حمل می‌کند، پس تکرار این فراخوانی بی‌خطر است.
audience پیش‌فرض را می‌توان مانند هر audience دیگری تغییر نام داد و توصیف کرد، اما نه می‌توان حذفش کرد و نه می‌توان از آن کم کرد. هر دو با 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 نویسهٔ hex. نام‌ها یکتا نیستند، پس همین است که باید در پیکربندی ذخیره‌شده بیاید.
namestr- هنگام نوشتن فاصله‌های اضافی حذف می‌شود، از 1 تا 120 نویسه. دو audience می‌توانند یک نام داشته باشند، چون audience با id خود آدرس‌دهی می‌شود.
descriptionstr | None- متن آزاد برای کسی که بعداً فهرست را می‌خواند. وقتی کسی چیزی ننوشته باشد `None` است، و `None` صریح در `update` آن را پاک می‌کند.
builtinAudienceBuiltin | str | None- `default` دقیقاً روی یک ردیف در هر فضای کاری، همان گروه مخاطبی که همهٔ مخاطبان را نگه می‌دارد، و `None` روی هر گروه مخاطبی که کسی ساخته باشد. نوع باز می‌ماند، با `str` در کنار مقدار literal، تا گروه درون‌ساختی که بعدها افزوده شود کدی را که با این نوع تایپ شده نشکند.
contactCountint- تعداد مخاطبان درون audience، که در لحظهٔ خواندن شمرده می‌شود نه از حافظهٔ نهان. دو خواندن در دو سوی یک `contacts.create` به‌اندازهٔ یک با هم اختلاف دارند.
lastContactAtstr | None- ISO-8601 به وقت UTC، زمانی که تازه‌ترین مخاطب به این گروه مخاطب پیوست. تا وقتی گروه خالی است `None` است.
createdAtstr- ISO-8601 به وقت UTC، زمان ساخته‌شدن audience. ترتیب فهرست را پس از audience پیش‌فرض تعیین می‌کند.
updatedAtstr- ISO-8601 به وقت UTC، که با تغییر نام یا تغییر توصیف جلو می‌رود. تغییر عضویت آن را دست نمی‌زند.
پارامترها: audiences.list_contacts
limitint- شمار مخاطبان در هر صفحه: عددی صحیح از ۱ تا ۲۰۰، با پیش‌فرض ۵۰.
cursorstr- `nextCursor` صفحهٔ قبل، که با همان `q`، `source` و `sort` فرستاده می‌شود. نشانگری که به مخاطبی بیرون از این گروه اشاره کند 400 `invalid_cursor` می‌دهد.
qstr- در نام و نشانی جست‌وجو می‌کند، تا ۲۰۰ نویسه. اگر در صفحهٔ نخست هیچ چیز دقیقاً جور نشود، به‌جایش نوشتارهای نزدیک برگردانده می‌شوند، و صفحه‌های بعدی به همان شیوه جست‌وجو را ادامه می‌دهند.
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- ISO-8601 به وقت UTC، زمانی که مخاطب به این گروه پیوسته است. بیرون آوردن مخاطب و افزودن دوباره‌اش آن را از نو آغاز می‌کند.
unsubscribedAtstr | None- ISO-8601 به وقت UTC، زمانی که مخاطب از یک ارسال گروهی به این گروه لغو اشتراک کرد، یا `None` تا وقتی مشترک است. مخاطبِ لغوشده در گروه می‌ماند و ارسال‌های گروهی به آن از او رد می‌شوند. بیرون آوردن و افزودن دوباره‌اش، او را از نو مشترک می‌کند.
افزودن و برداشتن گروهی
add_contacts و remove_contacts مقدار {'emails': [...]} را با ۱ تا ۲۰۰ نشانی می‌گیرند و یک گروه را با یک درخواست تغییر می‌دهند. 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]- تا ۵۰ شناسهٔ گروه مخاطب، که با ویرگول به هم پیوسته فرستاده می‌شوند. برای همهٔ گروه‌ها آن را نفرستید. شناسه‌ای که گروه مخاطبی در این فضای کاری نیست 404 `audience_not_found` می‌دهد.
daysint- بازه تا چه اندازه به عقب می‌رود، ۱ تا ۱۰۹۵. وقتی نه `days` داده شود و نه `minutes`، ۳۰ است.
minutesint- بازه به دقیقه، ۱ تا ۱۵۷۶۸۰۰، برای بازه‌ای کوتاه‌تر از یک روز. وقتی هر دو داده شوند، بر `days` اولویت دارد.
grainTrackingGrain- اندازهٔ هر بخش: `day` (پیش‌فرض)، `hour` یا `minute`.
offset_minutesint- اختلاف ساعت بیننده با UTC به دقیقه، -840 تا 840، تا بخش‌های روزانه و ساعتی از مرز محلی او آغاز شوند. پیش‌فرض 0.
پاسخ
sincestr- ISO-8601 به وقت UTC، آغاز نخستین بخش.
untilstr- ISO-8601 به وقت UTC، لحظهٔ خواندن.
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()مرجع کامل