Контакты, аудитории и рассылки

Четыре пространства имён охватывают людей, которым вы пишете. Контакты это адресная книга рабочего пространства, аудитории это именованные списки контактов, рассылка отправляет одно письмо всем в нескольких аудиториях, а список подавления хранит адреса, на которые рабочее пространство не отправляет. Каждая команда вызывает один метод SDK, поэтому страницы SDK описывают те же вызовы подробнее.

• —У контакта нет идентификатора. Ключом, который принимает каждая команда contacts, служит его адрес, без пробелов по краям и в нижнем регистре, поэтому [email protected] и [email protected] это один контакт. У аудитории идентификатор aud_, у рассылки brd_, а у записи о подавлении тот идентификатор, который выводит suppressions list.
• —Каждый контакт входит в аудиторию по умолчанию, пока он существует. Эту аудиторию нельзя удалить, очистить или проредить, и её builtin равен default.
• —Адресная книга принадлежит рабочему пространству, поэтому каждый участник и каждый ключ читают и пишут одну и ту же.
• —Каждое пространство имён откликается и на форму единственного числа, как в openemail contact get, и работают обычные псевдонимы: ls, show, new, edit и rm. В suppressions, где глаголы называются add и remove, new ведёт к add, а rm к remove.

Адресная книга рабочего пространства: люди, которым участник писал из редактора приложения, плюс все, кого сохранили вручную. Приходящая почта никого не добавляет, как и отправка через API или CLI.

Именованные списки контактов, до 100 в рабочем пространстве. Прежде чем адрес попадёт в аудиторию, он должен быть контактом, кроме как через import-contacts, который сохраняет новые адреса по ходу дела.

Одно письмо всем в не более чем 10 аудиториях, отправленное отдельной копией каждому человеку, с заполненными полями подстановки и ссылкой для отписки. Каждая копия это обычное письмо со своим идентификатором msg_, событиями и вебхуками.

Адреса, на которые это рабочее пространство не отправляет: жёсткие отказы и жалобы, записанные по мере появления, и любой адрес, который вы добавили вручную. Отправка на такой адрес отклоняется для этого получателя до того, как что-то уйдёт.

Большинству команд нужен scope чтения или записи их пространства имён. Нескольким нужен другой, потому что они читают или меняют что-то ещё:

• —Ключ, ограниченный определёнными адресами или доменами, читает и пишет ту же адресную книгу, что и любой другой ключ. Он видит только рассылки, отправленные с адреса или домена, который ему выдан, получает из list-people одни сохранённые контакты и получает отказ 422 capability_unsupported от contacts list-threads, activity, block и unblock, а также от suppressions add и remove.
• —Вход через браузер участника, у которого есть доступ только к некоторым адресам, получает отказ 422 capability_unsupported в каждой команде contacts, audiences и broadcasts. suppressions add отклоняет вход через браузер любого, кроме владельца рабочего пространства.

Соберите аудиторию из файла, а затем посчитайте, до кого дошла бы рассылка ей. import-contacts сохраняет адреса, которые ещё не контакты, и повторный запуск ничего не создаёт и не добавляет дважды.

[  { "email": "[email protected]", "name": "Ada Lovelace" },  { "email": "[email protected]", "name": "Grace Hopper" },  { "email": "[email protected]" }]

AUDIENCE=$(openemail audiences create --name 'Product updates' --json | jq -r .id)openemail audiences import-contacts "$AUDIENCE" --contacts @contacts.jsonopenemail broadcasts preview --audience-ids "$AUDIENCE"

Проверьте рассылку с --dry-run, который выводит запрос и ничего не отправляет, а затем отправьте её. Рассылка создаётся сразу и отправляется в фоне, поэтому опрашивайте get, чтобы следить за ней. В этом теле нет {{unsubscribeUrl}}, поэтому каждая копия получает однострочный футер для отписки.

{  "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>",  "scheduledAt": "2026-10-01T09:00:00Z"}

openemail broadcasts send --data @broadcast.json --dry-runBROADCAST=$(openemail broadcasts send --data @broadcast.json --yes --json | jq -r .id)openemail broadcasts get "$BROADCAST"openemail broadcasts stats "$BROADCAST" --grain day

Посмотрите, до кого рассылка не дошла. --ndjson выводит по одному получателю в строке, а --all --json один документ со всеми страницами.

openemail broadcasts list-recipients brd_5a8c1e3f7b2d94a06c8e1f3b --filter bounced --ndjson | jq -r .emailopenemail broadcasts list-recipients brd_5a8c1e3f7b2d94a06c8e1f3b --filter not_opened --all --json | jq ".items | length"openemail suppressions list --reason bounce --all --max 50

Скопируйте подписанных участников одной аудитории в другую. jq превращает поток в тело, которое принимает add-contacts, а --data - читает его из stdin. --max 200 ограничивает его 200 адресами, которые принимает один вызов.

openemail audiences list-contacts aud_9f2c4b7e1a0d63d84c5f2e7b --statuses subscribed --max 200 --ndjson \  | jq -s '{ emails: map(.email) }' \  | openemail audiences add-contacts aud_1c4e7a9b2d0f36e85a7c1b4d --data -

Удалите все контакты одного домена, записанные редактором. delete-many принимает до 200 адресов за вызов, поэтому xargs -n 200 делит более длинный список. Сначала проверьте пакеты с --dry-run, потому что отмены нет.

openemail contacts list --source auto --all --ndjson \  | jq -r 'select(.email | endswith("@old-vendor.example")) | .email' > leaving.txtxargs -n 200 openemail contacts delete-many --dry-run < leaving.txtxargs -n 200 openemail contacts delete-many --yes < leaving.txt

Прекратите отправку на адрес, снова разрешите другой и заблокируйте отправителя. removable говорит, какие строки примет suppressions remove.

openemail suppressions add --email [email protected]openemail suppressions list --q [email protected] --json | jq -r '.items[] | select(.removable) | .id'openemail suppressions remove 7b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e --yesopenemail contacts block [email protected]

Эти команды просят подтверждения в терминале перед запуском:

• —--yes подтверждает за вас. Без присмотра, с --json или --no-input, в CI или без терминала, команда, которая спросила бы, останавливается с Refusing to run unattended. Pass --yes to confirm. и кодом выхода 2.
• —--dry-run выводит запрос, который отправила бы команда, и завершается с кодом 0, ничего не спрашивая и ничего не меняя.
• —При входе через браузер audiences delete сначала спрашивает код подтверждения, как веб-приложение. --yes никогда его не пропускает, а без присмотра команда останавливается с кодом выхода 4. Заранее запустите openemail verify или используйте API-ключ, у которого код не спрашивают никогда.
• —audiences empty никогда не спрашивает код подтверждения, поэтому проверьте идентификатор, прежде чем передавать --yes.

Каждая команда, которая выводит список, читает одну страницу. Если осталось ещё, передайте выведенный курсор в --cursor с теми же фильтрами или прочитайте всё:

• —--all читает все страницы и передаёт элементы потоком: таблицей в терминале и по одному JSON-объекту в строке при передаче в конвейер или с --ndjson.
• —--max <n> останавливается после стольких элементов и подразумевает --all.
• —--json выводит один документ { items, hasMore, nextCursor }, в том числе с --all.
• —Неверный или устаревший курсор даёт 400 invalid_cursor. Начните заново без него.

• —contacts create отклоняет адрес, который уже есть в книге, с 409 contact_exists, поэтому повтор никогда не перезапишет имя, которое кто-то исправил. contacts save никогда не отказывает: он сохраняет, оставляет или возвращает адрес, в каком бы состоянии тот ни был.
• —contacts delete принимает и адрес, который встречался только в почте, и это убирает человека из list-people. Почта остаётся. Отмены нет: если снова сохранить адрес, контакт начнётся без имени, без заметок и без аудиторий, кроме аудитории по умолчанию.
• —Адрес это сама суть контакта, поэтому contacts update не может его изменить. Перенос контакта это delete и create.
• —contacts set-photo читает изображение из файла или из stdin через -. Передайте --content-type, например image/jpeg: без него изображение может уйти как application/octet-stream, и сервер отклонит его с 422 invalid_image.
• —broadcasts send --scheduled-at принимает время ISO 8601, например 2026-10-01T09:00:00Z, или длительность ISO 8601, например PT2H или P1D, до 365 дней вперёд. Короткие задержки, которые принимает send --at, например 2h, здесь отклоняются.
• —Поля подстановки работают в --subject, --html и --text: {{firstName}}, {{lastName}}, {{name}}, {{email}} и {{unsubscribeUrl}}, у каждого может быть запасное значение после черты, как в {{firstName|there}}. Тело без {{unsubscribeUrl}} получает однострочный футер для отписки. Шаблон отправляется как есть, поэтому ставьте ссылку в шаблон.
• —Рассылка сверяется с месячным лимитом отправок тарифа до того, как что-либо будет записано, и каждая копия считается одной отправкой. Рассылка, которую лимит не покрывает, отклоняется с 429 send_quota_exceeded, и после неё ничего не остаётся.
• —Передавайте свой --idempotency-key в broadcasts send, если скрипт может повторить этот шаг. С тем же ключом в ответ приходит уже созданная рассылка, а новая не отправляется.
• —Контакт, отписавшийся от рассылки, остаётся в аудитории с заполненным unsubscribedAt, и следующие рассылки этой аудитории его пропускают. audiences list-contacts --statuses unsubscribed перечисляет таких.
• —Жёсткий отказ остаётся в списке подавления. suppressions remove отклоняет его с 409 suppression_not_removable, а removable в каждой строке сообщает об этом заранее.