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

add-x-msys-api-header-metadata

<domain>

Какие заголовки письма копируются в метаданные для SparkPost
в конфигурации это строкаadd-x-msys-api-header-metadata noneвнутри блока <domain>
Три условия, при которых строка не работает

Умолчания нет. Значение — пары имя=header_ЗАГОЛОВОК через запятую: слева имя поля метаданных на стороне службы, справа — заголовок письма, откуда взять значение.

Условий, при которых строка не работает, руководство называет три, и все в одном абзаце:

Не задана родительская add-x-msys-api-header — директива игнорируется. Заголовок службы уже стоит в письме — игнорируется. Узел настроен удалять названный заголовок — строка «может оказаться неэффективной».

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

Главная ловушка — третье условие. Список вычищаемых заголовков (remove-header) обычно пишут один раз и забывают, а он живёт в блоке источника — далеко от этой строки в блоке получателя. Заголовок, попавший в оба списка, тихо не доедет до метаданных, и руководство описывает это осторожно: «может оказаться неэффективной».

Вторая половина: условия молчаливые. Ни одно из четырёх не даёт ошибки применения. Строка стоит в конфигурации, выглядит рабочей, а метаданные пусты — и понять, какое из условий сработало, можно только перебором.

Что делает Хаб. Не пишет: перенаправление через SparkPost не задействовано.

Если бы задействовали — третье условие сработало бы сразу: Хаб пишет remove-header со списком служебных заголовков платформ во всех источниках подачи, и попытка перенести любой из них в метаданные оказалась бы бесполезной.

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

Что ставить. Значение — пары; выбирать приходится, что переносить:

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

Заголовок для переноса должен быть своим и приходить снаружи: добавленные узлом не годятся по устройству, а вычищаемые не доедут.

Синтаксис, отсутствие умолчания и все четыре условия неработоспособности — из руководства, § 3.3.10.113.2. Оценка «условия молчаливые» наша.
Пример в конфигурации
# заголовок должен приходить снаружи и не попадать в список вычищаемых
<domain {sparkpost}>
    add-x-msys-api-header true
    add-x-msys-api-header-metadata job=header_X-MyJobId</domain>
Слева имя поля метаданных у службы, справа — заголовок письма. Если тот же заголовок стоит в списке вычищаемых у источника, перенос не сработает.
жёлтым — — имена директив, голубым — блоки. Так же они подсвечены и в тексте карточки.
▲

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

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

Переносят заголовок, который узел сам же вычищает

§ 3.3.10.113.2

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

Переносят заголовок, добавленный самим узлом

§ 3.3.10.113.2

Чем чреватоДля таких заголовков строка не работает по устройству. Отметка о приёме, дописанный идентификатор письма и им подобные в метаданные не попадут.
Как заметитьМетаданные пусты именно у тех полей, что берутся из добавленных узлом заголовков.
Как правильноПереносить только заголовки, приходящие от подающей стороны.
Совместимость
PowerMTA 6.0
описана в руководстве этой версии · платформа: любая
С какой версии директива доступна, вендор указывает не для всех — здесь пометки нет. Имя встречается и в издании руководства 5.0.
Справочные данные
Синтаксис
add-x-msys-api-header-metadata <mapping>
Значения
пары имя=header_ЗАГОЛОВОК через запятую
Умолчание
none § 3.3.10.113.2
Применение
reload, перезапуск не нужен
Очередь
уже поставленное в очередь не затронет
Где писать
<domain>
Сколько раз
один раз в блоке
Всё здесь — из руководства, с разделом.
Наследование
Директива живёт в <domain> и подчиняется слиянию блоков получателей. Но зависит она от того, что написано в блоке источника: список вычищаемых заголовков живёт там, и он способен сделать эту строку бесполезной.
⇄

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

1 связь

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

auth-username<domain>Строка работает только внутри перенаправления трафика, а оно начинается с авторизации у службы. § 3.3.10.113.2

Как проверить на узле
Проверять надо три места сразу — иначе не понять, какое условие сработало:
grep -n 'add-x-msys-api-header' /etc/pmta/config
grep -n 'remove-header' /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Все 135 директив блока →