API

REST API для интеграции с системой фильтрации почты Спаморез.

Основы API

Endpoint

https://my.spamorez.ru/panelv32/api/?token=ВАШ_API_ТОКЕН

Формат запроса

Запросы отправляются методом POST с телом в формате JSON. Поддерживается также GET с параметрами в URL.

POST body (JSON)

{
    "request": "имя_модуля",
    "action":  "действие",
    "параметры": "значения"
}

Авторизация

Токен передаётся в параметре URL token. Сгенерировать токен можно в панели управления → «Токены доступа».

Поддерживаемые модули

request	Описание
`tracker`	История обработки писем
`message`	Детали конкретного письма
`queue`	Очередь отправки
`domains`	Список доменов
`domain`	Управление одним доменом
`boxes`	Список ящиков
`box`	Управление одним ящиком
`whitelists`	Белый список
`blacklists`	Чёрный список
`stats`	Статистика

Трекер

История обработки почтовых сообщений.

Список писем

Запрос

{
    "request": "tracker",
    "action":  "list",
    "status":  "quarant",
    "date":    "day",
    "mail_to": "example.com"
}

Параметр	Описание	Пример
`status`	Статус письма	quarant, deliv, reject, error
`date`	Период	day, lastday, week, month
`subject`	Тема письма	"Акция"
`mail_from`	Отправитель	"sender@domain.com"
`mail_to`	Получатель	"user@example.com"
`smid`	ID письма	"2508200002183574501"
`ip_from`	IP отправителя	"192.168.1.1"
`perpage`	Записей на странице	50
`page`	Номер страницы	1

Ответ

{
    "perpage": "50",
    "page": 1,
    "records": 453,
    "pages": 10,
    "rows": {
        "1": {
            "byid":        {"key": "byid",    "val": "2508200002183574501"},
            "status":      {"key": "status",  "val": "zonde",
                            "view": "Ловушки СПАМ"},
            "date":        {"key": "date",    "val": "сегодня в 00:02, Ср"},
            "subject":     {"key": "subject", "val": "Тендер ПАО «ЛУКОЙЛ»"},
            "mail_from":   {"key": "mail_from","val": "srm@lukoil.com"},
            "mail_to":     {"key": "mail_to", "val": "yuri@mydomain.ru"},
            "status_info": {"key": "status_info","val": "237"}
        }
    }
}

Детальная информация о письме

Запрос

{
    "request": "message",
    "action":  "view",
    "byid":    "2508200324264421504"
}

Поле	Описание
`byid`	Уникальный ID письма
`smid`	Spamorez Message ID
`date`	Дата и время обработки
`helo`	EHLO приветствие отправителя
`ip_from`	IP-адрес отправителя
`mail_from`	Email отправителя
`mail_to`	Email получателя
`subject`	Тема письма
`msize`	Размер письма
`quarantine`	Флаг карантина (0/1)
`status`	Код статуса обработки
`status_text`	Текстовое описание статуса
`head`	Заголовки письма (raw)
`log`	Лог обработки письма

Ответ (успех)

{
    "records": 1,
    "code": "success",
    "rows": {
        "1": {
            "byid":        {"key":"byid","val":"2508200324264421504"},
            "smid":        {"key":"smid","val":"2508200324264421504"},
            "date":        {"key":"date","val":"20 Августа в 03:24:26"},
            "ip_from":     {"key":"ip_from","val":"10.255.7.3"},
            "mail_from":   {"key":"mail_from","val":"sender@example.com"},
            "mail_to":     {"key":"mail_to","val":"sn@mydomain.ru"},
            "subject":     {"key":"subject","val":"Тема письма"},
            "msize":       {"key":"msize","val":"2.5 Kb"},
            "quarantine":  {"key":"quarantine","val":"0"},
            "status_text": {"key":"status_text",
                "val":"Письмо доставлено по назначению"},
            "head":        {"key":"head","val":"Заголовки письма..."},
            "log":         {"key":"log","val":"Лог обработки..."}
        }
    }
}

Ответ (ошибка)

{
    "records": 0,
    "code":   "failed",
    "error":  "notfound",
    "text":   "Запись не найдена",
    "module": "tracker",
    "request": "view"
}

Очередь писем

Список очереди

{
    "request":  "queue",
    "action":   "list",
    "mail_from": "sn@mov.ru",
    "date":     "day",
    "perpage":  50,
    "page":     1
}

Принудительная отправка всех

{
    "request": "queue",
    "action":  "sendall"
}

Частое использование sendall может привести к блокировке со стороны принимающих серверов из-за интенсивной отправки.

Ответ (список)

{
    "records": 1, "code": "success",
    "rows": {
        "1": {
            "byid":      {"key":"byid","val":"2508221749084133220"},
            "status":    {"key":"status","val":"queue",
                          "view":"В очереди"},
            "date":      {"key":"date","val":"сегодня в 17:49, Пт"},
            "mail_from": {"key":"mail_from","val":"sn@mov.ru"},
            "mail_to":   {"key":"mail_to",
                "val":"recipient@example.com"},
            "status_info":{"key":"status_info","val":"340"}
        }
    },
    "actions": ["list", "sendall"],
    "module": "tracker", "request": "list"
}

Ответ (sendall)

{
    "code":       "success",
    "message":    "Все письма из очереди отправлены",
    "sent_count": 15,
    "module":     "tracker",
    "request":    "sendall"
}

Управление доменами

Список доменов

Запрос

{
    "request": "domains",
    "action":  "list",
    "active":  "1",
    "domain":  "example"
}

Ответ

{
    "records": 1, "code": "success",
    "rows": {
        "1": {
            "byid":      {"key":"byid","val":"mydomain.ru"},
            "status":    {"key":"status","val":"normal",
                          "view":"Активные"},
            "domain":    {"key":"domain","val":"mydomain.ru"},
            "emailcnt":  {"key":"emailcnt","val":"31"},
            "mx_fail":   {"key":"mx_fail","val":"0"},
            "mxs_mx":    {"key":"mxs_mx",
                "val":"001:mx.spamorez.ru;020:mx1.spamorez.ru"},
            "spamlevel": {"key":"spamlevel","val":"6982 (90 %)"}
        }
    }
}

Просмотр настроек домена

Запрос

{"request":"domain","action":"view","byid":"mydomain.ru"}

Поле	Описание
`smtpserver`	Основной SMTP-сервер доставки
`smtpserver2`	Резервный SMTP-сервер
`port`	Порт SMTP-сервера
`databytes`	Лимит размера писем
`num1`	Уровень спам-фильтрации (1–10)
`boxtype`	Тип управления ящиками (add_safe / manual)
`masquarade`	Маскировка отправителя (yes/no)
`weblearn`	Веб-обучение антиспама (enable/disable)
`dkim_selector`	DKIM-селектор
`dkim_pub`	DKIM-публичный ключ

Добавление домена

Запрос

{
    "request":    "domain",
    "action":     "add",
    "domain":     "newdomain.ru",
    "smtpserver": "mx.yandex.ru",
    "boxtype":    "add_safe",
    "masquarade": "yes"
}

Параметр	Обязательный
`domain`	Да
`smtpserver`	Да
`smtpserver2`	Нет
`port`	Нет
`boxtype`	Нет
`masquarade`	Нет
`comment`	Нет

Ответ (успех)

{
    "code": "success",
    "rows": {"byid": 1855},
    "actions": ["view","save","add","delete","check"],
    "module": "domain", "request": "add"
}

Ошибка валидации

{
    "code":  "failed",
    "error": "fields",
    "rows": {
        "smtpserver": {
            "errors": [{"error":"badhost",
                "error_text":"Хост указан неверно"}]
        }
    },
    "text": "Ошибка при заполнении полей"
}

Изменение домена

Запрос

{
    "request":    "domain",
    "action":     "save",
    "byid":       "mydomain.ru",
    "smtpserver": "mx1.yandex.ru",
    "num1":       "7.00"
}

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

{"code":"success","rows":[{
    "field":"smtpserver","old":"mx.yandex.ru","val":"mx1.yandex.ru"
}]}

Удаление домена

Запрос

{
    "request": "domain",
    "action":  "delete",
    "byid":    "example.ru"
}

Перед удалением необходимо удалить все почтовые ящики домена. Операция необратима.

Код ошибки	Описание
`notfound`	Домен не найден
`access_denied`	Нет прав на удаление
`has_mailboxes`	На домене есть ящики
`has_aliases`	На домене есть алиасы
`system_domain`	Системный домен

Управление ящиками

Список ящиков

{
    "request": "boxes",
    "action":  "list",
    "domain":  "mydomain.ru",
    "status":  "active",
    "email":   "admin@",
    "perpage": 100,
    "page":    1
}

Просмотр ящика

{
    "request": "box",
    "action":  "view",
    "byid":    "user@mydomain.ru"
}

Добавление ящика

{
    "request":  "box",
    "action":   "add",
    "email":    "newuser@mydomain.ru",
    "password": "securepassword123"
}

Изменение ящика

{
    "request":  "box",
    "action":   "save",
    "byid":     "user@mydomain.ru",
    "comment":  "Администратор",
    "password": "newpassword456"
}

Удаление ящика

{
    "request": "box",
    "action":  "delete",
    "byid":    "user@mydomain.ru"
}

Поле ответа	Описание
`byid`	Email ящика (ID)
`status`	active / disabled / zonde
`email`	Полный email адрес
`emailcnt`	Количество писем
`boxunused`	Флаг неиспользуемого
`boxnospam`	Отключение фильтрации
`comment`	Комментарий
`spamlevel`	Уровень спама

Код ошибки	Описание
`notfound`	Ящик не найден
`already_exists`	Ящик уже существует
`invalid_email`	Неверный формат email
`domain_not_exists`	Домен не существует
`password_too_weak`	Слишком слабый пароль
`quota_exceeded`	Превышена квота ящиков

Белый список

Список записей

{
    "request":    "whitelists",
    "action":     "list",
    "status":     "personal",
    "address":    "gmail.com",
    "to_address": "user@mydomain.ru"
}

Добавление записи

{
    "request":    "whitelists",
    "action":     "add",
    "address":    "partner@company.com",
    "to_address": "user@mydomain.ru",
    "status":     "personal",
    "comment":    "Надежный партнер"
}

Изменение / удаление

{
    "request": "whitelists",
    "action":  "save",
    "byid":    "61539",
    "comment": "Новый комментарий"
}

{"request":"whitelists","action":"delete","byid":"61539"}

Пример ответа списка

{
    "records": 483, "code": "success",
    "rows": {
        "1": {
            "byid":       {"key":"byid","val":"61539"},
            "status":     {"key":"status","val":"personal",
                           "view":"Персональные"},
            "address":    {"key":"address",
                "val":"partner@gmail.com"},
            "to_address": {"key":"to_address",
                "val":"eg@mydomain.ru"},
            "comment":    {"key":"comment",
                "val":"ООО Партнёр"}
        }
    }
}

Записи с to_address: "(для всех)" применяются ко всем получателям домена. Добавление целого домена (gmail.com) может значительно снизить уровень фильтрации.

Чёрный список

Список записей

{
    "request": "blacklists",
    "action":  "list",
    "status":  "domain",
    "address": "*.ru"
}

Добавление записи

{
    "request":    "blacklists",
    "action":     "add",
    "address":    "*.spammer.com",
    "to_address": "(для всех)",
    "status":     "domain",
    "comment":    "Известный спаммер"
}

Изменение / удаление

{"request":"blacklists","action":"save",
 "byid":"192605","comment":"Обновлено"}

{"request":"blacklists","action":"delete","byid":"192605"}

Тип	Пример address
Email	`spammer@example.com`
Домен	`*.example.com`
IP	`192.168.1.1`
IP-диапазон	`192.168.1.*`

status	Описание
`personal`	Персональная запись
`domain`	Для всего домена
`ip`	По IP-адресу

Статистика

Получение статистики

{
    "request":   "stats",
    "action":    "list",
    "period":    "month",
    "domain":    "example.com"
}

Детальная статистика

{
    "request": "stats",
    "action":  "view",
    "byid":    "2024-08",
    "domain":  "example.com"
}

Параметр	Описание
`period`	day, week, month, year
`domain`	Фильтр по домену
`date_from`	Начало периода (YYYY-MM-DD)
`date_to`	Конец периода (YYYY-MM-DD)

Коды ошибок

HTTP	Статус	Описание
200	Success	Запрос выполнен успешно
400	Bad Request	Неверный синтаксис запроса
401	Unauthorized	Неверный или отсутствующий токен
403	Forbidden	Доступ запрещён
404	Not Found	Объект не найден
500	Internal Error	Внутренняя ошибка сервера

error	Описание
`notfound`	Запись не найдена
`access_denied`	Нет доступа
`denied`	Нет прав на операцию
`fields`	Ошибки валидации полей
`required`	Обязательное поле не заполнено
`badhost`	Неверный формат хоста
`invalid_email`	Неверный формат email
`invalid_domain`	Неверный формат домена
`invalid_address`	Неверный формат адреса
`invalid_ip`	Неверный формат IP
`already_exists`	Запись уже существует
`domain_exists`	Домен уже существует
`has_mailboxes`	Домен содержит ящики
`quota_exceeded`	Превышена квота
`password_too_weak`	Слишком слабый пароль
`queue_empty`	Очередь пуста
`database_error`	Ошибка базы данных

Примеры запросов

GET-запрос с параметрами в URL

cURL

curl -X GET \
  'https://my.spamorez.ru/panelv32/api/?token=YOUR_TOKEN&request=tracker&action=list&mail_from=newsletter@company.com&date=week&status=quarant' \
  -H 'Content-Type: application/json'

POST-запрос с JSON-телом

cURL

curl -X POST \
  'https://my.spamorez.ru/panelv32/api/?token=YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "request": "tracker",
    "action":  "list",
    "mail_from": "billing@service.com",
    "date":    "month",
    "status":  "deliv",
    "subject": "Счет",
    "perpage": 100,
    "page":    1
}'

Python

import requests, json

TOKEN = "ВАШ_API_ТОКЕН"
URL   = f"https://my.spamorez.ru/panelv32/api/?token={TOKEN}"

def api(payload):
    r = requests.post(URL, json=payload,
                      headers={"Content-Type": "application/json"})
    return r.json()

# Список писем в карантине
print(api({"request":"tracker","action":"list","status":"quarant","date":"day"}))

# Добавить домен
print(api({"request":"domain","action":"add",
           "domain":"example.ru","smtpserver":"mail.example.ru"}))

# Работа с очередью
queue = api({"request":"queue","action":"list","perpage":100})
if queue.get("records", 0) > 0:
    api({"request":"queue","action":"sendall"})

API v4 — текущая версия панели управления. Сохраняет совместимость с форматом запросов v3, но возвращает упрощённый JSON без промежуточной обёртки {"key":…,"val":…}, поддерживает Bearer-авторизацию и расширяет набор модулей.

Основы API v4

Endpoint

https://my.spamorez.ru/panel/api/

Авторизация

Поддерживаются два способа — старый (токен в URL, обратная совместимость) и новый (Bearer-заголовок):

Вариант 1 — токен в URL (v3-совместимый)

POST https://my.spamorez.ru/panel/api/?token=ВАШ_ТОКЕН

Вариант 2 — Bearer-заголовок (рекомендуется)

POST https://my.spamorez.ru/panel/api/
Authorization: Bearer ВАШ_ТОКЕН
Content-Type: application/json

Формат запроса

Тот же JSON-формат, что и в v3. Дополнительно принимается application/x-www-form-urlencoded.

{
    "request": "модуль",
    "action":  "действие",
    "параметры": "значения"
}

Формат ответа — что изменилось

В v3 каждое поле данных оборачивается в объект {"key":"…","val":"…"}. В v4 данные возвращаются напрямую:

v3 — вложенный формат

{
    "rows": {
        "1": {
            "byid":   {"key":"byid","val":"123"},
            "domain": {"key":"domain","val":"example.ru"},
            "status": {"key":"status","val":"normal",
                       "view":"Активные"}
        }
    }
}

v4 — плоский формат

{
    "code": "success",
    "records": 1,
    "page":    1,
    "pages":   1,
    "perpage": 50,
    "rows": [
        {
            "byid":   "123",
            "domain": "example.ru",
            "status": "normal"
        }
    ]
}

Поле view (читаемое название статуса) вынесено в отдельное поле с суффиксом _label, если нужно: например, "status_label": "Активные".

Пагинация

Все списочные методы поддерживают параметры page и perpage (по умолчанию 50, максимум 500). В ответе: records (всего записей), pages (всего страниц), page (текущая).

Трекер v4

Запросы идентичны v3, ответ в плоском формате.

Запрос

{
    "request": "tracker",
    "action":  "list",
    "status":  "quarant",
    "date":    "day",
    "mail_to": "example.com",
    "perpage": 50,
    "page":    1
}

Ответ

{
    "code":    "success",
    "records": 453,
    "page":    1, "pages": 10, "perpage": 50,
    "rows": [
        {
            "byid":      "2508200002183574501",
            "status":    "zonde",
            "date":      "2025-08-20 00:02:00",
            "subject":   "Тендер ПАО «ЛУКОЙЛ»",
            "mail_from": "srm@lukoil.com",
            "mail_to":   "yuri@mydomain.ru"
        }
    ]
}

Детали письма

Запрос

{
    "request": "message",
    "action":  "view",
    "byid":    "2508200324264421504"
}

Ответ

{
    "code": "success", "records": 1,
    "rows": [{
        "byid":        "2508200324264421504",
        "date":        "2025-08-20T03:24:26Z",
        "ip_from":     "10.255.7.3",
        "mail_from":   "sender@example.com",
        "mail_to":     "sn@mydomain.ru",
        "subject":     "Тема письма",
        "msize_bytes": 2560,
        "quarantine":  false,
        "status":      "5",
        "status_text": "Письмо доставлено",
        "head":        "…raw headers…",
        "log":         "…processing log…"
    }]
}

Домены v4

Список доменов

{
    "request": "domains",
    "action":  "list",
    "active":  1
}

Просмотр домена

{
    "request": "domain",
    "action":  "view",
    "byid":    "example.ru"
}

Добавление

{
    "request":    "domain",
    "action":     "add",
    "domain":     "newdomain.ru",
    "smtpserver": "mx.yandex.ru"
}

Изменение

{
    "request":    "domain",
    "action":     "save",
    "byid":       "example.ru",
    "smtpserver": "mx1.yandex.ru",
    "num1":       7.0
}

Удаление

{
    "request": "domain",
    "action":  "delete",
    "byid":    "example.ru"
}

Ответ (список)

{
    "code": "success", "records": 2,
    "rows": [
        {
            "byid":      "example.ru",
            "status":    "normal",
            "domain":    "example.ru",
            "emailcnt":  31,
            "mx_fail":   0,
            "mxs_mx":    "mx.spamorez.ru",
            "spam_pct":  90
        }
    ]
}

Ответ (add)

{
    "code": "success",
    "byid": 1855,
    "module": "domain",
    "request": "add"
}

Ответ (save)

{
    "code": "success",
    "changed": [
        {"field":"smtpserver",
         "old":"mx.yandex.ru",
         "val":"mx1.yandex.ru"}
    ]
}

Ящики v4

Запросы идентичны v3. Новые поля в ответах:

Новое поле	Описание
`created_at`	Дата создания ящика (ISO 8601)
`last_mail_at`	Дата последнего письма
`spam_cnt_7d`	Спам за 7 дней
`deliv_cnt_7d`	Доставлено за 7 дней

Белый и чёрный список v4

Запросы идентичны v3. В ответе поле address_type явно указывает тип: email, domain, ip — вместо выведения типа из формата строки.

Пример ответа blacklists/list (v4)

{
    "code": "success", "records": 95,
    "rows": [
        {
            "byid":         "192605",
            "status":       "domain",
            "address":      "*.askona.ru",
            "address_type": "domain",
            "to_address":   null,
            "comment":      "Askona"
        }
    ]
}

Правила обработки (новое в v4)

Модуль rules — новый в v4, управляет правилами фильтрации.

Список правил

{
    "request": "rules",
    "action":  "list",
    "domain":  "example.ru"
}

Создание правила

{
    "request":  "rule",
    "action":   "add",
    "username": "example.ru",
    "rl_name":  "Заблокировать рассылку",
    "rl_logic": "and",
    "rl_stop":  1,
    "criteria": [
        {"rc_type":"from",
         "rc_match":"wildcard",
         "rc_value":"*@newsletter.com",
         "rc_negate": false}
    ],
    "actions": [
        {"ra_type":"discard","ra_params":"{}"}
    ]
}

Ответ (список)

{
    "code": "success", "records": 3,
    "rows": [
        {
            "byid":     "42",
            "rl_name":  "Заблокировать рассылку",
            "rl_logic": "and",
            "rl_stop":  true,
            "active":   true,
            "criteria_cnt": 1,
            "actions_cnt":  1
        }
    ]
}

Ответ (add)

{
    "code":   "success",
    "byid":   42,
    "module": "rule",
    "request":"add"
}

rc_type	Условие
`from`	Отправитель (From)
`rcpt`	Получатель (To)
`ip`	IP отправителя
`subject`	Тема письма
`keyword`	Ключевое слово в теле
`header`	Заголовок письма

ra_type	Действие	ra_params
`spam`	Пометить как спам	`{"score": 10}`
`discard`	Удалить без уведомления	`{}`
`reject`	Отклонить с кодом 550	`{"message": "Blocked"}`
`forward_email`	Переслать на email	`{"email": "copy@example.ru"}`
`forward_server`	Переслать на SMTP-сервер	`{"host": "mx.other.ru", "port": 25}`
`tag_subject`	Добавить префикс к теме	`{"prefix": "[SPAM]"}`
`add_header`	Добавить заголовок	`{"name": "X-Tag", "value": "promo"}`

Ошибки v4

Формат ошибки унифицирован:

{
    "code":    "failed",
    "error":   "notfound",
    "text":    "Домен не найден",
    "module":  "domain",
    "request": "view",
    "fields": {
        "smtpserver": [
            {"error": "badhost", "text": "Хост указан неверно"}
        ]
    }
}

Поле fields появляется только при ошибке fields и содержит детали по каждому полю. Коды ошибок те же, что в v3, плюс новые:

Код (новые в v4)	Описание
`rule_not_found`	Правило не найдено
`criterion_not_found`	Критерий правила не найден
`action_not_found`	Действие правила не найдено
`invalid_token`	Токен недействителен или отозван
`rate_limited`	Превышен лимит запросов

Примеры запросов v4

cURL с Bearer-токеном

curl -X POST https://my.spamorez.ru/panel/api/ \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"request":"tracker","action":"list","status":"quarant","date":"day"}'

Python

import requests

TOKEN = "ВАШ_API_ТОКЕН"
BASE  = "https://my.spamorez.ru/panel/api/"

session = requests.Session()
session.headers.update({
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json"
})

def api(payload):
    r = session.post(BASE, json=payload)
    r.raise_for_status()
    return r.json()

# Список доменов
domains = api({"request":"domains","action":"list"})
for row in domains.get("rows", []):
    print(row["domain"], row["emailcnt"])

# Создать правило
rule = api({
    "request":  "rule",
    "action":   "add",
    "username": "example.ru",
    "rl_name":  "Блокировать рассылку",
    "rl_logic": "and",
    "criteria": [{"rc_type":"from","rc_match":"wildcard",
                  "rc_value":"*@promo.com"}],
    "actions":  [{"ra_type":"discard","ra_params":"{}"}]
})
print("Создано правило:", rule.get("byid"))