ارسال به گروه‌های مخاطب

یک پیام را برای همهٔ افراد یک یا چند گروه مخاطب می‌فرستد، به شکل نسخه‌ای جدا برای هر نفر که از روی مخاطبِ همان نفر شخصی‌سازی شده است. هر نسخه دقیقاً یک گیرنده دارد و cc یا bcc ندارد، پس هیچ‌کس نمی‌بیند برای چه کس دیگری رفته، و هر نسخه ایمیلی معمولی است با شناسهٔ msg_، رویدادها، ردیابی و وب‌هوک‌های خودش. فراخوانی بی‌درنگ 202 پاسخ می‌دهد و ارسال در پس‌زمینه ادامه دارد، پس آن را با GET /broadcasts/{id} دنبال کنید.

به emails:send و audiences:read نیاز دارد. audienceIds از ۱ تا ۱۰ شناسه دارد. متن از html و/یا text یا از یک template ذخیره‌شده می‌آید، هرگز هر دو، و subject الزامی است مگر آنکه قالب آن را بدهد.

curl -X POST "$OE/broadcasts" -H "$AUTH" -H 'content-type: application/json' -d '{  "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" },  "scheduledAt": "PT2H"}'

{  "object": "broadcast",  "id": "brd_5a8c1e3f7b2d94a06c8e1f3b",  "status": "scheduled",  "mode": "live",  "source": "api",  "audienceIds": ["aud_4c1b8e2a7d9f05c36b4e8a71"],  "from": "Acme <[email protected]>",  "subject": "{{firstName|Hello}}, the September release is out",  "counts": {    "recipients": 412,    "created": 0,    "skipped": 0,    "failedToQueue": 0,    "queued": 0,    "sending": 0,    "sent": 0,    "failed": 0,    "cancelled": 0  },  "lastError": null,  "scheduledAt": "2026-09-23T14:00:00.000Z",  "startedAt": null,  "completedAt": null,  "cancelledAt": null,  "createdAt": "2026-09-23T12:00:00.000Z",  "updatedAt": "2026-09-23T12:00:00.000Z",  "replayed": false}

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

ارسال، گروه‌ها را هر بار ۵۰ نفر پیش می‌برد و هر نسخه را به همان مسیری می‌سپارد که POST /emails به کار می‌برد، پس هر نسخه مثل هر پیام دیگری دوباره تلاش، ردیابی و گزارش می‌شود. POST /broadcasts/preview عددی را که این فراخوانی از آن شروع می‌کند برمی‌گرداند، بی‌آنکه چیزی بفرستد.

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

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

هر نسخه List-Unsubscribe و List-Unsubscribe-Post: List-Unsubscribe=One-Click دارد. همین است که به برنامهٔ ایمیل اجازه می‌دهد دکمهٔ لغو اشتراکِ خودش را نشان دهد، و همان چیزی است که ارائه‌دهندگان بزرگ صندوق ایمیل از ایمیل انبوه می‌خواهند.

متن html یا text که خودش {{unsubscribeUrl}} را نگذارد، یک پانویس یک‌خطی می‌گیرد: "You are receiving this because you are on this mailing list. Unsubscribe". قالب دقیقاً همان‌طور که هست فرستاده می‌شود، پس {{unsubscribeUrl}} را در قالب بگذارید.

پیوند صفحه‌ای با دکمهٔ لغو اشتراک باز می‌کند، پس پویشگر پیوندی که آن را بگیرد اشتراک کسی را لغو نمی‌کند، در حالی که درخواست یک‌کلیکیِ برنامهٔ ایمیل بی‌درنگ لغو می‌کند. در هر دو حال فرد در همهٔ گروه‌هایی که این ارسال گروهی برایشان رفته لغوشده علامت می‌خورد، که به شکل unsubscribedAt در GET /audiences/{id}/contacts دیده می‌شود. گروه‌های دیگرش، مخاطبش و ایمیلی که تک‌تک برایش فرستاده می‌شود دست نمی‌خورند.