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

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"}} reach = client.broadcasts.preview(draft)puts reach[:recipients], reach[:unsubscribed], reach[:suppressed] broadcast = client.broadcasts.send(draft) latest = client.broadcasts.get(broadcast[:id])while %w[scheduled queued sending].include?(latest[:status])  sleep 5  latest = client.broadcasts.get(broadcast[:id])end client.broadcasts.iterate_recipients(broadcast[:id]) do |copy|  puts copy[:email], copy[:status], copy[:opens], copy[:clicks]end bounced = client.broadcasts.list_recipients(broadcast[:id], filter: "bounced")bounced.items.each { |row| puts "#{row[:emailId]} #{row[:email]}" } copy = client.broadcasts.get_recipient(broadcast[:id], "msg_01dad25067bc4dac966d515d")puts copy[:subject], copy[:bouncedAt] stats = client.broadcasts.stats(broadcast[:id], grain: "day")puts stats.dig(:totals, :opened), stats.dig(:totals, :clicked), stats.dig(:totals, :unsubscribed) lately = client.broadcasts.stats(broadcast[:id], days: 1)puts lately.dig(:window, :opened) later = client.broadcasts.send(draft, scheduledAt: "P1D")client.broadcasts.cancel(later[:id]) history = client.broadcasts.list(audience_id: draft[:audienceIds].first)puts latest[:status], latest.dig(:counts, :sent), history.items.size month = client.broadcasts.analytics(days: 30)month[:broadcasts].each do |row|  puts row[:subject], row[:sent], row[:opened]end

ارسال گروهی یک پیام را برای همهٔ افراد یک یا چند گروه مخاطب می‌فرستد، به شکل نسخه‌ای جدا برای هر نفر. هر نسخه دقیقاً یک گیرنده دارد و 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.

broadcast = client.broadcasts.send(  audienceIds: ["aud_4c1b8e2a7d9f05c36b4e8a71"],  from: "Acme <[email protected]>",  subject: "Doors open on Friday",  text: "Hi {{firstName|there}}, doors open at nine. Unsubscribe: {{unsubscribeUrl}}",  scheduledAt: Time.now + 3600,  idempotency_key: "doors-open-2026-10") puts broadcast[:id], broadcast[:status], broadcast[:replayed]

فیلدهای یک ارسال گروهی آرگومان‌های کلیدواژه‌ای یا یک Hash هستند و نام‌های camelCase در API را نگه می‌دارند (audienceIds:، scheduledAt:). idempotency_key: و api_key: گزینه‌های فراخوانی‌اند و هرگز به‌صورت فیلد فرستاده نمی‌شوند. کلیدواژه‌هایی که کنار یک Hash داده شوند در آن ادغام می‌شوند، پس send(draft, scheduledAt: "P1D") همان پیش‌نویس را یک روز بعد می‌فرستد. scheduledAt: یک Time، یک DateTime، یک String با قالب ISO 8601 یا مدتی مانند PT2H می‌گیرد، و Time به‌صورت یک لحظهٔ UTC فرستاده می‌شود. preview از آنچه به آن می‌دهید فقط audienceIds را می‌فرستد، پس همان Hash ارسال send را می‌پذیرد. پاسخ یک Hash با کلیدهای Symbol است، پس broadcast[:status] وضعیت را می‌خواند.

subject، html و text برای هر نفر از روی مخاطبش پر می‌شوند. {{firstName}} نخستین واژهٔ نام مخاطب است، {{lastName}} بقیهٔ آن، {{name}} نام کامل، {{email}} نشانی‌ای که نسخه به آن می‌رود و {{unsubscribeUrl}} پیوندی که اشتراکش را لغو می‌کند.

هر فیلد پس از یک خط یک مقدار جایگزین می‌پذیرد که وقتی مخاطب مقداری برای آن ندارد به کار می‌رود، پس {{firstName|there}} برای مخاطبی که بی‌نام ذخیره شده "there" می‌شود. مقدارها در html گریزانده می‌شوند و هر {{…}} دیگری دقیقاً همان‌طور که نوشته شده می‌ماند.

برای فرستادن یک قالب ذخیره‌شده، template: را به‌جای html: و text: بدهید، به‌صورت یک Hash با id و به‌طور اختیاری version، props و slots. همان پنج مقدار به شکل prop به آن می‌رسند، ولی فقط propهایی که قالب اعلام می‌کند، پس قالبی که firstName را اعلام کند آن را می‌گیرد و قالبی که اعلام نکند هرگز به خاطرش رد نمی‌شود. هر چه در props آن باشد برای همهٔ نسخه‌ها یکسان می‌رود.

هر نسخه سرآیندهای لغو اشتراک با یک کلیک را دارد که به برنامهٔ ایمیل اجازه می‌دهند دکمهٔ لغو اشتراکِ خودش را نشان دهد، چیزی که ارائه‌دهندگان بزرگ صندوق ایمیل از ایمیل انبوه می‌خواهند. متن html یا text که خودش {{unsubscribeUrl}} را نگذارد یک پانویس یک‌خطی با پیوند می‌گیرد. قالب دقیقاً همان‌طور که هست فرستاده می‌شود، پس {{unsubscribeUrl}} را در قالب بگذارید.

لغو اشتراک، فرد را در همهٔ گروه‌هایی که آن ارسال گروهی برایشان رفته لغواشتراک‌کرده علامت می‌زند، و audiences.list_contacts آن را در unsubscribedAt ردیف او نشان می‌دهد، همان‌طور که صفحهٔ «گروه‌های مخاطب» توضیح می‌دهد. او در گروه و در دفترچهٔ نشانی‌ها می‌ماند، گروه‌های دیگرش دست نمی‌خورند، و ایمیلی که تک‌تک برایش فرستاده می‌شود همچنان می‌رود. بیرون آوردن او از گروه و افزودن دوباره‌اش او را از نو مشترک می‌کند.

ارسال گروهی به هر مخاطبی می‌رسد که دست‌کم در یکی از audienceIds باشد، یک بار هر چند تا که او را داشته باشند. از مخاطبی که از همهٔ آن گروه‌هایی که در آن‌هاست لغو اشتراک کرده، و از نشانی‌ای که پس از برگشت یا شکایت، یا چون کسی آن را افزوده، در فهرست توقیف است رد می‌شود. مخاطبی که پس از send ولی پیش از رسیدن ارسال به او به یکی از گروه‌ها افزوده شود، دریافت می‌کند.

preview همان عددها را بدون ارسال برمی‌گرداند: recipients، unsubscribed و suppressed. sendی که به هیچ‌کس نرسد 422 no_recipients را به‌صورت OpenEmail::ValidationError raise می‌کند.

get مقدار counts را زنده از نسخه‌ها می‌خواند، پس در طول ارسال آن را پیاپی بخوانید، با sleep میان فراخوانی‌ها همان‌طور که نمونهٔ بالا انجام می‌دهد. status از scheduled یا queued به sending می‌رود و وقتی هر نسخهٔ سپرده‌شده رفته یا ناموفق شده روی sent می‌ایستد. تا وقتی نسخه‌ها هنوز منتظرند sending می‌ماند، حتی پس از آنکه completedAt بگوید به آخرین نفر رسیده. failed یعنی کل ارسال گروهی متوقف شده و lastError دلیلش را می‌گوید: دیگر نمی‌شود از نشانی from فرستاد، قالب دیگر بارگذاری نمی‌شود، طرح در میانهٔ راه تمام شد، خودِ ارسال پیاپی ناموفق ماند، یا حتی یک نسخه هم نوشته نشد.

cancel ارسال گروهی‌ای را که scheduled، queued یا sending است متوقف می‌کند. کسی دیگر افزوده نمی‌شود و هر نسخه‌ای که هنوز منتظر است لغو می‌شود، در حالی که نسخه‌های رفته برگرداندنی نیستند. وقتی همهٔ نسخه‌ها رفته باشند، cancel خطای 409 broadcast_not_cancellable را به‌صورت OpenEmail::ConflictError raise می‌کند، و لغو یک ارسال گروهیِ لغوشده آن را با همان حالتی که هست برمی‌گرداند.

list_recipients یک OpenEmail::Page از کسانی که ارسال گروهی برایشان رفت برمی‌گرداند، یک ردیف برای هر نسخه، مرتب‌شده بر اساس نشانی، با items، has_more? و next_cursor. list_all_recipients همهٔ صفحه‌ها را در یک Array می‌پیماید، و iterate_recipients هر بار یک نسخه را به یک بلاک yield می‌کند و صفحهٔ بعد را فقط وقتی حلقه بخواهد می‌گیرد. بدون بلاک یک Enumerator برمی‌گرداند. limit: از 1 تا 200 است با پیش‌فرض 50، و cursor: با همان filter: و q: پس داده می‌شود.

OpenEmail::BROADCAST_RECIPIENT_FILTERS هر فیلتر را نام می‌برد، و q: نشانی و نام را بدون توجه به بزرگی و کوچکی حروف جست‌وجو می‌کند. باز کردن‌ها و کلیک‌ها پراکسی‌های تصویر و اسکنرهای پیوند را کنار می‌گذارند، و وقتی ارسال گروهی با ردیابی خاموش رفته باشد 0 می‌مانند.

get_recipient(id, email_id) یک نسخه را برمی‌گرداند: همان ردیف، به‌علاوهٔ subject، html و text دقیقاً همان‌طور که آن شخص دریافت کرد، با فیلدهای ادغامِ پرشده و پیوند لغو اشتراک مخصوص خودش. emailId یک ردیف را به‌عنوان email_id بدهید. HTML مربوط به پیش از افزودن ردیابی باز کردن و کلیک است. email_idی که نسخه‌ای از این ارسال گروهی نیست 404 recipient_not_found را raise می‌کند، و ارسال گروهی ناشناخته 404 broadcast_not_found را، هر دو به‌صورت OpenEmail::NotFoundError.

stats مجموع‌ها و یک سری را برمی‌گرداند. totals نسخه‌های sent، delivered، bounced، complained و failed را می‌شمارد، با pending برای آن‌هایی که هنوز در انتظارند، و افرادی را که opened، clicked و unsubscribed شدند، با opens و clicks به‌عنوان شمار رویدادها. series پراکنده است و قدیمی‌ترین اول، یک بازه برای هر grain: (minute، hour یا day، با پیش‌فرض hour) که در آن چیزی رخ داده، بریده‌شده در منطقهٔ زمانی‌ای که offset_minutes: دقیقه در شرق UTC است. برای منطقهٔ زمانی محلی Time.now.utc_offset / 60 را بدهید. هر کس را یک بار می‌شمارد، در نخستین باری که برایش رخ داد، پس جمعش با مجموع‌ها برابر می‌شود.

برای اینکه آنچه اخیراً رخ داده را هم بخوانید، days: یا minutes: را به stats بدهید. آنگاه window آنچه را درون آن تحویل شده، برگشت خورده، هرزنامه گزارش شده، باز شده، کلیک شده و لغو اشتراک شده می‌شمارد، و series فقط بازه‌های همان پنجره را نگه می‌دارد، در حالی که totals همچنان کل ارسال گروهی را در بر می‌گیرد. بدون هیچ‌کدام، window برابر nil است.

send، get و cancel هرکدام یکی از این‌ها را برمی‌گردانند، یک Hash با کلیدهای Symbol، و send مقدار replayed را هم می‌افزاید. list یک OpenEmail::Page از آن‌ها برمی‌گرداند، تازه‌ترین اول، و list_all و iterate همهٔ صفحه‌ها را می‌پیمایند. preview یک Hash با audienceIds، recipients، unsubscribed و suppressed برمی‌گرداند. list_recipients یک OpenEmail::Page از ردیف‌های گیرنده برمی‌گرداند، get_recipient یک ردیف را همراه محتوایش برمی‌گرداند، و stats یک Hash با broadcastId، grain، totals، window و series برمی‌گرداند. analytics یک Hash با totals، series و یک ردیف برای هر ارسال گروهی در broadcasts برمی‌گرداند. زمان‌ها Stringهایی با قالب ISO 8601 هستند که Time.iso8601 آن‌ها را تجزیه می‌کند.

هر ردیف list_recipients، list_all_recipients و iterate_recipients، به‌صورت یک Hash با کلیدهای Symbol. Hashی که get_recipient برمی‌گرداند subject، html و text را هم می‌افزاید.