Demo
Demo
База знаний PMTA›Точка API§ 8.3.2

Списки адресов через API настройки

критично

address list operations
Правка конфигурации запросом

Создаёт, читает, дополняет и удаляет списки адресов и доменов — например, списки подавления — запросами, без правки файлов.

Пути. GET /config/address-lists — имена всех списков; GET, POST, PUT, PATCH и DELETE на /config/address-lists/имя — прочитать, создать, заменить, дополнить и удалить список; DELETE на …/addresses/адрес, …/hashed-addresses/адрес и …/domains/домен — убрать одну запись. Тела запросов и ответы — JSON.

Сначала включают: точка работает только при http-enable-api-config yes, по умолчанию выключено.

Объекты, созданные так, правятся только через API: в файле конфигурации их нет, и два способа описать одно и то же не сходятся. MTA хранит их в /var/lib/pmta/config-api.

Чтение пройдёт без ключа с адреса уровня operator и выше в http-access; любое изменение — только с ключом из http-api-key в заголовке X-API-Key.

Главная ловушка — код 200 при ошибке. Отказ приходит с кодом 200, а исход — в поле status (fail) и в тексте message. И текст бывает сбивающим: удаление списка, который где-то используется, отклоняет перечитывание, и ответ говорит «no such address list», хотя список на месте.
Что делает Хаб. Не пользуется: http-enable-api-config на узлах не включён, а свои списки адресов — для приёма жалоб и отказов — Хаб пишет прямо в файл конфигурации.
Рекомендуемые значения

Какой метод что делает:

Метод Путь Действие
GET /config/address-lists имена всех списков
GET …/имя содержимое списка
POST …/имя создать; если список есть — ошибка
PUT …/имя заменить целиком; если списка нет — ошибка
PATCH …/имя дополнить; повторы молча пропускаются
DELETE …/имя или …/имя/addresses/адрес удалить список или одну запись
Пути, методы, включение директивой, хранение в /var/lib/pmta/config-api и ошибки с кодом 200 — из руководства (§ 8.3, § 8.3.2, § 8.3.4). Разбор ловушки — наш.
Пример в конфигурации
# дополнить список подавления двумя адресами
curl -s -X PATCH 'http://127.0.0.1:8080/config/address-lists/suppress' -H 'X-API-Key: KEY' -H 'Content-Type: application/json' -d '{"addresses":["a@example.com","b@example.com"]}'
PATCH дополняет список, PUT заменил бы его целиком. После каждого изменения MTA сам перечитывает конфигурацию.
жёлтым — — имена директив, голубым — блоки. Так же они подсвечены и в тексте карточки.
Совместимость
PowerMTA 6.0
описана в руководстве этой версии · платформа: любая
С какой версии директива доступна, вендор указывает не для всех — здесь пометки нет. Имя встречается и в издании руководства 5.0.
⇄

Связанные записи

3 связи

Зависит от

Настройка через API и файл не сходятсяМеханизм, который здесь и виден. § 8.3

Работают в паре

Посчитать хешТа же выдача из командной строки. inference

Где это видно

Списки адресов — именованные и безымянныеМеханизм, который здесь и виден. § 8.3.2

Сюда ссылаются

Две точки подключения — и два разных поведенияСписки правятся по HTTP, без правки конфигурации и без перезагрузки, — этим механизм и интересен. § 11.15

Как проверить на узле
Проверить, включено ли API и что в нём заведено:
grep -n 'http-enable-api-config' /etc/pmta/config
curl -s 'http://127.0.0.1:8080/config/address-lists'
ls /var/lib/pmta/config-api/
Ответ со status fail — смотреть message: там причина отказа перечитывания. Пустой перечень при включённой директиве — списков через API не заводили.
◇

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

3 статьи

◇Списки адресов — именованные и безымянныеСписок адресов, доменов, образцов или хешей; именованный подключается директивами вроде подавления, безымянный живёт внутри процессора входящей почты.◇Настройка через API и файл не сходятсяОбъекты, созданные через интерфейс настройки, в файле не правятся: два источника правды о конфигурации не сходятся.◇Две точки подключения — и два разных поведенияСписок, подключённый к источнику, отвергает получателя при подаче или отбивает письмо позже; подключённый к адресу отправки или пулу — всегда принимает и отбивает.

В Хабе
Цена ошибки
обратимо: вредит, пока стоит
Сценарии
Подавление адресов · Разделение отправителей
Важность
критично