ارسال‌های گروهی
`broadcasts.preview`، `send`، `list`، `list_all`، `iterate`، `get`، `list_recipients`، `list_all_recipients`، `iterate_recipients`، `get_recipient`، `stats`، `analytics` و `cancel`.
همهٔ متدها
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.
هر send یک Idempotency-Key دارد، کلید شما از راه idempotency_key= یا کلیدی که SDK می‌سازد، پس تلاش دوباره پس از خطای شبکه با ارسال گروهی‌ای که تلاش نخست ساخته پاسخ می‌دهد به‌جای دو بار فرستادن. preview، get، cancel و همهٔ خواندن‌ها را می‌توان بی‌خطر تکرار کرد و دوباره تلاش می‌شوند.
فیلدهای ادغام
subject، html و text برای هر نفر از روی مخاطبش پر می‌شوند. {{firstName}} نخستین واژهٔ نام مخاطب است، {{lastName}} بقیهٔ آن، {{name}} نام کامل، {{email}} نشانی‌ای که نسخه به آن می‌رود و {{unsubscribeUrl}} پیوندی که اشتراکش را لغو می‌کند.
هر فیلد پس از یک خط یک مقدار جایگزین می‌پذیرد که وقتی مخاطب مقداری برای آن ندارد به کار می‌رود، پس {{firstName|there}} برای مخاطبی که بی‌نام ذخیره شده "there" می‌شود. مقدارها در html گریزانده می‌شوند و هر {{…}} دیگری دقیقاً همان‌طور که نوشته شده می‌ماند.
برای فرستادن قالب ذخیره‌شده، template را به‌جای html و text بدهید. همان پنج مقدار به شکل prop به آن می‌رسند، ولی فقط propهایی که قالب اعلام می‌کند، پس قالبی که firstName را اعلام کند آن را می‌گیرد و قالبی که اعلام نکند هرگز به خاطرش رد نمی‌شود. هر چه در template.props باشد برای همهٔ نسخه‌ها یکسان می‌رود.
لغو اشتراک
هر نسخه سرآیندهای لغو اشتراک با یک کلیک را دارد که به برنامهٔ ایمیل اجازه می‌دهند دکمهٔ لغو اشتراکِ خودش را نشان دهد، چیزی که ارائه‌دهندگان بزرگ صندوق ایمیل از ایمیل انبوه می‌خواهند. متن html یا text که خودش {{unsubscribeUrl}} را نگذارد یک پانویس یک‌خطی با پیوند می‌گیرد. قالب دقیقاً همان‌طور که هست فرستاده می‌شود، پس {{unsubscribeUrl}} را در قالب بگذارید.
لغو اشتراک، فرد را در همهٔ گروه‌هایی که آن ارسال گروهی برایشان رفته لغوشده علامت می‌زند و AudienceContactResource.unsubscribedAt آن را در audiences.list_contacts نشان می‌دهد. او در گروه و در دفترچهٔ نشانی می‌ماند، گروه‌های دیگرش دست نمی‌خورند و ایمیلی که تک‌تک برایش فرستاده می‌شود همچنان می‌رود. بیرون آوردن او از گروه و افزودن دوباره‌اش او را از نو مشترک می‌کند.
چه کسانی رد می‌شوند
ارسال گروهی به هر مخاطبی می‌رسد که دست‌کم در یکی از audienceIds باشد، یک بار هر چند تا که او را داشته باشند. از مخاطبی که از همهٔ آن گروه‌هایی که در آن‌هاست لغو اشتراک کرده، و از نشانی‌ای که پس از برگشت یا شکایت، یا چون کسی آن را افزوده، در فهرست توقیف است رد می‌شود. مخاطبی که پس از send ولی پیش از رسیدن ارسال به او به یکی از گروه‌ها افزوده شود، دریافت می‌کند.
preview همان عددها را بی‌ارسال برمی‌گرداند: recipients، unsubscribed و suppressed. یک send که به هیچ‌کس نرسد 422 no_recipients را raise می‌کند.
کل ارسال پیش از نوشتن هر چیزی با سهمیهٔ ماهانهٔ ارسالِ طرح سنجیده می‌شود، پس ارسال گروهی‌ای که سهمیه پوشش ندهد 429 send_quota_exceeded را raise می‌کند و چیزی از خود به جا نمی‌گذارد. هر نسخه یک ارسال حساب می‌شود.
وضعیت و پیشرفت
get مقدار counts را زنده از نسخه‌ها می‌خواند، پس در طول ارسال آن را پرس‌وجو کنید. status از scheduled یا queued به sending می‌رود و وقتی هر نسخهٔ سپرده‌شده رفته یا ناموفق شده روی sent می‌ایستد. تا وقتی نسخه‌ها هنوز منتظرند sending می‌ماند، حتی پس از آنکه completedAt بگوید به آخرین نفر رسیده. failed یعنی کل ارسال گروهی متوقف شده و lastError دلیلش را می‌گوید: دیگر نمی‌شود از نشانی from فرستاد، قالب دیگر حل نمی‌شود، طرح در میانهٔ راه تمام شد، خودِ ارسال بارها ناموفق ماند، یا حتی یک نسخه هم نوشته نشد.
cancel ارسال گروهی‌ای را که scheduled، queued یا sending است متوقف می‌کند. کسی دیگر افزوده نمی‌شود و هر نسخه‌ای که هنوز منتظر است لغو می‌شود، در حالی که نسخه‌های رفته برگرداندنی نیستند. وقتی همهٔ نسخه‌ها رفته باشند، cancel خطای 409 broadcast_not_cancellable را raise می‌کند، و لغو یک ارسال گروهیِ لغوشده آن را با همان حالتی که هست برمی‌گرداند.
به چه کسانی رسید
list_recipients یک صفحه از کسانی که ارسال گروهی برایشان رفت برمی‌گرداند، یک سطر برای هر نسخه، مرتب‌شده بر اساس نشانی، به شکل دیکشنری‌ای با items، hasMore و nextCursor. list_all_recipients همهٔ صفحه‌ها را در یک فهرست می‌پیماید و iterate_recipients هر بار یک نسخه yield می‌کند و صفحهٔ بعد را فقط وقتی حلقه بخواهد می‌گیرد. limit از 1 تا 200 است و پیش‌فرض آن 50 است، و یک cursor با همان filter و q بازگردانده می‌شود.
| filter | نگه می‌دارد |
|---|---|
| pending | نسخه‌هایی که هنوز در صف، زمان‌بندی‌شده یا در حال ارسال‌اند. |
| sent | نسخه‌هایی که فرستاده شدند. |
| delivered | نسخه‌هایی که سرور گیرنده پذیرفت. |
| opened | نسخه‌هایی که دست‌کم یک بار باز شدند. |
| not_opened | نسخه‌هایی که فرستاده شدند و هرگز باز نشدند. |
| clicked | نسخه‌هایی با دست‌کم یک کلیک ردیابی‌شده. |
| bounced | نسخه‌هایی که برگشت خوردند. |
| complained | نسخه‌هایی که آن شخص به عنوان هرزنامه گزارش کرد. |
| failed | نسخه‌هایی که ناموفق بودند یا لغو شدند. |
| unsubscribed | افرادی که پس از ارسال گروهی لغو اشتراک کردند. |
BROADCAST_RECIPIENT_FILTERS هر فیلتر را نام می‌برد، و q نشانی و نام را بدون توجه به کوچکی و بزرگی حروف جست‌وجو می‌کند. باز کردن‌ها و کلیک‌ها پراکسی‌های تصویر و اسکنرهای لینک را کنار می‌گذارند، و وقتی ارسال گروهی با ردیابی خاموش فرستاده شده باشد 0 می‌مانند.
get_recipient(id, email_id) یک نسخه برمی‌گرداند: همان سطر، به‌علاوهٔ subject، html و text دقیقاً همان‌طور که آن شخص دریافت کرد، با فیلدهای ادغام پرشده و پیوند لغو اشتراک مخصوص خودش. HTML مربوط به پیش از افزودن ردیابی باز شدن و کلیک است. یک email_id که نسخه‌ای از این ارسال گروهی نیست خطای 404 recipient_not_found را raise می‌کند، و یک ارسال گروهی ناشناخته خطای 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. هر نفر را یک بار می‌شمارد، در نخستین باری که برایش رخ داد، پس جمعش با مجموع‌ها برابر است.
کلیدی که به نشانی‌ها یا دامنه‌های خاصی محدود است فقط به ارسال‌های گروهی‌ای دسترسی دارد که از نشانی یا دامنه‌ای که دارد فرستاده شده‌اند. list، list_all و iterate بقیه را کنار می‌گذارند، و get، متدهای گیرندگان، stats و cancel برای آن‌ها 404 broadcast_not_found را raise می‌کنند.
پاسخ: BroadcastResource
get و cancel هر کدام یکی از این‌ها را برمی‌گردانند، و send یک SentBroadcastResource برمی‌گرداند، یعنی همان فیلدها به‌علاوهٔ replayed، که وقتی پاسخ همان ارسال گروهی‌ای باشد که فراخوانی پیشینی با همان کلید idempotency ساخته بود True است. list صفحه‌ای از آن‌ها برمی‌گرداند، دیکشنری‌ای با items، hasMore و nextCursor، تازه‌ترین اول، و list_all و iterate همهٔ صفحه‌ها را می‌پیمایند. preview یک BroadcastPreviewResource برمی‌گرداند که audienceIds، recipients، unsubscribed و suppressed دارد. list_recipients صفحه‌ای از سطرهای BroadcastRecipientResource برمی‌گرداند، get_recipient یک BroadcastRecipientContentResource و stats یک BroadcastStatsResource.
idstr- دستگیرهٔ ماندگار، `brd_` و پس از آن 24 نویسهٔ hex.
statusBroadcastStatus- `scheduled`، `queued`، `sending`، `sent`، `cancelled` یا `failed`. `BROADCAST_STATUSES` هر کدام را نام می‌برد.
modeApiKeyMode- `live` یا `test`، بسته به کلیدی که آن را ساخته. نسخه‌های ارسال گروهیِ آزمایشی ارسال‌شده علامت می‌خورند و به هیچ‌کس تحویل داده نمی‌شوند.
sourceEmailSource | str- از کجا شروع شده: `api` برای کلید، `oauth` برای برنامهٔ متصل، `composer` برای خود برنامه، `mcp` برای دستیار.
audienceIdslist[str]- گروه‌هایی که برایشان فرستاده شده، هر کدام یک بار.
fromstr- نشانی‌ای که هر نسخه از آن فرستاده می‌شود.
subjectstr- موضوع همان‌طور که نوشته شده، با فیلدهای ادغام. خالی وقتی قالب موضوع را می‌دهد.
countsBroadcastCounts- `recipients` تخمینی است که هنگام `send` گرفته شده. `created` نسخه‌های نوشته‌شده را می‌شمارد، `skipped` کسانی را که چون نشانی‌شان تا آن موقع توقیف بود کنار گذاشته شدند، و `failedToQueue` کسانی را که نسخه‌شان نوشته نشد. `queued`، `sending`، `sent`، `failed` و `cancelled` نسخه‌ها را بر اساس وضعیتی که هر کدام الان دارد می‌شمارند.
lastErrorstr | None- اینکه ارسال گروهی چرا ناموفق شد، یا تازه‌ترین نسخه‌ای که نوشته نشد و چرا. تا وقتی مشکلی پیش نیامده `None` است.
scheduledAtstr | None- ISO-8601 به وقت UTC، زمانی که ارسال باید شروع شود. برای ارسال گروهی‌ای که بی‌درنگ فرستاده شده `None` است.
startedAtstr | None- ISO-8601 UTC، زمانی که ارسال به نخستین افراد رسید.
completedAtstr | None- ISO-8601 UTC، زمانی که به آخرین نفر رسید. پس از آن هنوز ممکن است نسخه‌هایی منتظر رفتن باشند.
cancelledAtstr | None- ISO-8601 UTC، زمانی که `cancel` آن را متوقف کرد.
createdAtstr- ISO-8601 UTC، زمانی که `send` فراخوانده شد. ترتیب فهرست را تعیین می‌کند.
updatedAtstr- ISO-8601 UTC، با پیشرفت ارسال به‌روز می‌شود.
پاسخ: BroadcastRecipientResource
هر سطر از list_recipients، list_all_recipients و iterate_recipients. BroadcastRecipientContentResource، از get_recipient، subject، html و text را اضافه می‌کند.
emailIdstr- شناسهٔ `msg_` نسخهٔ این شخص. `get_recipient` آن را همراه محتوایش می‌خواند و `emails.get` آن را به عنوان یک ایمیل ارسال‌شده می‌خواند.
contactIdstr | None- مخاطبی که نسخه برایش رفت، یا `None` وقتی مخاطب از آن پس حذف شده باشد.
emailstr- نشانی‌ای که نسخه به آن رفت.
namestr | None- نام روی مخاطب.
statusstr- وضعیت نسخه: `queued`، `scheduled`، `sending`، `sent`، `failed` یا `cancelled`.
sentAtstr | None- ISO-8601 UTC، زمانی که نسخه فرستاده شد.
deliveredAtstr | None- ISO-8601 UTC، زمانی که سرور گیرنده آن را پذیرفت، نخستین `email.delivered`.
bouncedAtstr | None- ISO-8601 UTC، زمانی که برگشت خورد، نخستین `email.bounced`.
complainedAtstr | None- ISO-8601 UTC، زمانی که آن شخص آن را به عنوان هرزنامه گزارش کرد، نخستین `email.complained`.
failurestr | None- دلیل ناموفق بودن نسخه، اگر ناموفق بود.
opensint- باز کردن‌های ثبت‌شده، بدون آن‌هایی که پراکسی‌های تصویر و اسکنرها ایجاد می‌کنند. وقتی ردیابی خاموش بود 0 است.
firstOpenAtstr | None- ISO-8601 UTC، نخستین باز کردن.
clicksint- کلیک‌های ثبت‌شده روی لینک‌های ردیابی‌شده، بدون اسکنرها.
firstClickAtstr | None- ISO-8601 UTC، نخستین کلیک.
unsubscribedAtstr | None- ISO-8601 UTC، زمانی که این شخص پس از ارسال، از طریق لینک آن یا به هر راه دیگری، از یکی از گروه‌های مخاطب ارسال گروهی لغو اشتراک کرد.
مرجع
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()مرجع کامل