Рассылки

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, поэтому никто не видит, кому ещё она ушла, и каждая копия — обычное письмо со своим id 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, чтобы отправить сохранённый шаблон. Те же пять значений приходят в него как пропсы, но только те, что объявляет шаблон, поэтому шаблон с 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.