Demo
Demo
База знаний PMTA›Блок <domain>›Директива§ 3.3.10.113.1

add-x-msys-api-header

<domain>

Добавлять ли заголовок с параметрами для SparkPost
в конфигурации это строкаadd-x-msys-api-header true для домена sparkpost, false для остальныхвнутри блока <domain>
Мост между настройками узла и настройками службы

Умолчание зависит от получателя: true для зарезервированного домена {sparkpost} и false для всех остальных.

Строка дописывает письму служебный заголовок X-MSYS-API — тот, которым задаются настройки на стороне SparkPost. Заодно она переносит метку задания письма в поле кампании службы, если метка есть.

Уже стоящий заголовок не трогается. Если подающая сторона поставила его сама, директива игнорируется целиком — значение остаётся её.

Работает всё это внутри механизма перенаправления трафика: руководство описывает его как способ добавить мощности, например на сезон. Домен {sparkpost} создаётся отдельно, и в нём задаются auth-username и auth-password — имя с необязательным номером субсчёта и ключ доступа службы.

Главная ловушка — кампания берётся из метки задания. Если метку никто не ставит, поле кампании в отчётах службы окажется пустым — и разбирать её статистику будет не по чему.

Метка задания у нас как раз не ставится: чтение заголовка с ней не включено ни в одном источнике подачи. То есть включение перенаправления потребовало бы сначала завести метки.

Вторая половина: номер субсчёта задаётся не здесь, а в имени пользователя авторизации — приставкой к нему. И если ключ доступа сам принадлежит субсчёту, номер в имени игнорируется.

Что делает Хаб. Не пишет: перенаправление трафика через SparkPost не задействовано, домена {sparkpost} в конфигурации нет.

Если бы задействовали — пришлось бы начинать не с этой строки, а с меток заданий: process-x-job у нас стоит в false, и переносить в кампанию было бы нечего.

Рекомендуемые значения

Что ставить. Умолчание почти всегда верно:

Значение Когда
не писать умолчание разное для {sparkpost} и прочих — и оба верны
false для {sparkpost} подающая сторона ставит заголовок сама и полнее
true для прочих получателей смысла нет: заголовок понимает только SparkPost

Третья строка — не рекомендация, а предупреждение: включённая у обычного получателя, строка добавит письму заголовок, который уедет получателю без всякой пользы.

Умолчания по получателям, перенос метки задания в кампанию и правило «уже стоящий заголовок не трогается» — из руководства, § 3.3.10.113.1. Синтаксис имени с субсчётом — § 3.3.10.113. Разбивка случаев наша.
Пример в конфигурации
# домен зарезервирован; ключ доступа и имя задают счёт службы
<domain {sparkpost}>
    auth-username SMTP_Injection:X-MSYS-SUBACCOUNT=123
    auth-password d41d8cd98f00b204e9800998ecf8427e
    add-x-msys-api-header true</domain>
Строка здесь повторяет умолчание для этого домена. Номер субсчёта задаётся в имени пользователя, а не ею — и игнорируется, если ключ доступа сам принадлежит субсчёту.
жёлтым — — имена директив, голубым — блоки. Так же они подсвечены и в тексте карточки.
▲

Типичные ошибки и проблемы

что делают не так и чем это кончается2 ошибки▶

Ждут имя кампании там, где нет метки задания

§ 3.3.10.113.1

Чем чреватоВ поле кампании переносится метка задания письма. Нет метки — поле пустое, и статистику службы не по чему разбирать.
Как заметитьОтчёты службы показывают трафик без разбивки по кампаниям.
Как правильноЗавести метки заданий при подаче — иначе переносить нечего.

Ищут настройку субсчёта среди этих строк

§ 3.3.10.113

Чем чреватоСубсчёт задаётся приставкой к имени пользователя авторизации, и там же он игнорируется, если ключ доступа сам принадлежит субсчёту. Ни одна из строк с приставкой sparkpost- его не задаёт.
Как заметитьТрафик уходит не на тот счёт службы, а настройки субсчёта в конфигурации не найти.
Как правильноСмотреть имя пользователя авторизации и происхождение ключа доступа.
Совместимость
PowerMTA 6.0
описана в руководстве этой версии · платформа: любая
С какой версии директива доступна, вендор указывает не для всех — здесь пометки нет. Имя встречается и в издании руководства 5.0.
Справочные данные
Синтаксис
add-x-msys-api-header <boolean>
Значения
yes | no | true | false
Умолчание
true для домена sparkpost, false для остальных § 3.3.10.113.1
Применение
reload, перезапуск не нужен
Очередь
уже поставленное в очередь не затронет
Где писать
<domain>
Сколько раз
один раз в блоке
Всё здесь — из руководства, с разделом.
Наследование
Директива живёт в <domain> и подчиняется слиянию блоков получателей. Особенность в умолчании: оно разное для зарезервированного домена {sparkpost} и для всех прочих — редкий случай, когда «не написано» означает разное у разных получателей.
⇄

Связанные директивы

1 связь

Без чего не работает

auth-username<domain>Счёт и субсчёт службы задаются в имени пользователя, а не этой строкой. § 3.3.10.113.1

Как проверить на узле
Настройку видно в конфигурации, следствие — в письме и в отчётах службы:
grep -n -A5 'domain {sparkpost}' /etc/pmta/config
grep -n 'process-x-job' /etc/pmta/config /etc/pmta/virtualhost.txt
Вторая команда важнее первой: без метки задания поле кампании в отчётах службы останется пустым. Само наличие заголовка проверяется письмом в контрольный ящик через тот же маршрут.
◇

Что ещё почитать

3 статьи

◇Ключ активации — условие установки, а не шаг после неёБез ключа активации от поддержки SparkPost MTA не ставится и не работает, а уровень лицензии задаёт потолок исходящих соединений: на стандартной всё сверх 200 игнорируется.◇Ограничения облакаОблака ограничивают исходящую почту через порт 25, пока не попросишь снять лимит, а их диапазоны адресов почтовики встречают с подозрением.◇Как перевести план отправки в железоДве постоянные, по которым считается любой узел: около 2 КБ памяти на каждого получателя в очереди и место под спул, пропорциональное суммарному размеру писем.

В Хабе
Цена ошибки
безопасно: неверное значение ничего не ломает
Сценарии
Планирование мощности
Соседние настройки блока <domain>:http-delivery-urlhttp-delivery-extra-headerssparkpost-sandboxsparkpost-ip-pooladd-x-msys-api-header-metadataВсе 135 директив блока →