ارسال‌های گروهی

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 بدهید. همان پنج مقدار به شکل prop به آن می‌رسند، ولی فقط propهایی که قالب اعلام می‌کند، پس قالبی که 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 دارد.