Email Inbox (приём писем как уведомлений)

Email Inbox — это «почтовый ящик», у которого вместо вашего IMAP — каналы Notifly. Создав ящик, вы получаете уникальный email-адрес вида <alias>@in.notifly.ru. Всё, что на него приходит, разбирается по правилам маршрутизации: каждое правило по фильтру решает, в какой канал и с каким заголовком/текстом отправить уведомление.

Это удобно, когда внешняя система умеет только email и научить её ходить в HTTP — слишком дорого:

• алёрты от хостингов, биллингов, RBL и регистраторов;
• уведомления от CI/CD, системы бэкапов, сторонних SaaS;
• transactional email от вашего же бекенда (заказы, регистрации) без отдельного канала push;
• алёрты от старых железных мониторингов, которые умеют только SMTP.

Два шага настройки

Ящик сам по себе не привязан к каналу — он только принимает почту. Маршрутизация выполняется отдельными правилами. Поэтому настройка состоит из двух шагов:

1. Создать ящик → получить адрес <alias>@in.notifly.ru и вписать его в настройки внешнего сервиса.
2. Добавить правило (или несколько) → указать фильтр (для какого письма срабатывать) и канал-получатель.

Если у ящика нет ни одного правила, а письмо пришло — оно тихо отбрасывается (никаких уведомлений не порождает). Письмо проверяется правилами по возрастанию position; для каждого совпавшего правила создаётся уведомление в его канале.

Как это работает

SMTP-отправитель ──► <alias>@in.notifly.ru
                     │
                     ▼
              Yandex Cloud Mail Trigger
                     │
                     ▼
        Cloud Function notifly-email
                     │  1. достать alias из адреса
                     │  2. найти EmailInbox по alias
                     │  3. прогнать письмо через правила ящика (по position)
                     │  4. для каждого совпавшего правила — title/message по шаблону
                     ▼
       INSERT messages + push в WebSocket (для каждого совпавшего правила)
                     │
                     ▼
        Все ваши клиенты получают уведомления

• Маршрутизация — по alias в локальной части адреса.
• Push — то же самое, что у обычного POST /message: моментальный фрейм по WebSocket плюс запись в БД для последующих GET /message.
• Опционально входящие письма сохраняются в историю (см. saveEvents ниже).

Шаг 1. Создание ящика

Через админку

1. Откройте app.notifly.ru → Email Inbox.
2. Нажмите «Создать ящик», заполните:
   • Название — для отображения, например «Алёрты Reg.ru».
   • Сохранять входящие — складывать ли тексты писем в историю (saveEvents).
3. В карточке появится сгенерированный email-адрес — это и есть аутентификация. Скопируйте его в настройки внешнего сервиса.

Через REST API

Тело запроса — EmailInboxParams: {name, saveEvents}. Поле appId у ящика нет — канал назначается правилами.

curl -X POST "$NOTIFLY_URL/email-inbox" \
     -H "Content-Type: application/json" \
     -H "X-Notifly-Key: <client-token>" \
     -d '{
       "name": "Алёрты Reg.ru",
       "saveEvents": true
     }'

В ответе придёт сам объект ящика с заполненным emailAddress:

{
  "id": 17,
  "name": "Алёрты Reg.ru",
  "alias": "a3f9c21b8e04",
  "emailAddress": "a3f9c21b8e04@in.notifly.ru",
  "saveEvents": true,
  "rules": [],
  "created": "2026-04-30T10:11:12Z",
  "lastUsed": null
}

alias — 12 hex-символов, генерируется автоматически и неизменяем.

Через MCP (для AI-ассистента)

Если у вас настроен MCP-сервер Notifly, просто попросите:

Создай Email Inbox с названием «Алёрты Reg.ru» и правило, которое шлёт в канал «Operations» письма, где from содержит @reg.ru. Пришли адрес.

Шаг 2. Правила маршрутизации

Правило (EmailInboxRule) описывает, какие письма ловить и куда их слать. У правила есть:

Поле	Назначение
appId	канал-получатель (обязателен)
name	имя правила для отображения
filter	условия срабатывания (см. ниже); пустой фильтр = «совпадает всегда»
titleTemplate	шаблон заголовка уведомления; пусто → тема письма
messageTemplate	шаблон текста уведомления; пусто → тело письма
priority	приоритет уведомления
enabled	включено ли правило (по умолчанию true)
position	порядок проверки (по возрастанию)

В шаблонах titleTemplate / messageTemplate доступны плейсхолдеры: {subject}, {body}, {from}, {to}, {date}, {alias}.

Фильтр

filter (EmailFilter) — это match плюс список conditions:

• match: "all" — должны выполниться все условия (AND, по умолчанию);
• match: "any" — достаточно одного условия (OR);
• пустой conditions означает «совпадает всегда» (правило по умолчанию).

Каждое условие (EmailFilterCondition) — это field, op, value (и caseSensitive, по умолчанию false).

Поля (field):

field	На чём проверяет
from	заголовок From (адрес или имя)
to	заголовок To (адрес)
subject	тема письма
body	текстовое тело письма
header	произвольный заголовок (имя — в headerName)

Операторы (op):

op	Смысл
contains	подстрока
not_contains	отсутствие подстроки
equals	точное совпадение
not_equals	точное несовпадение
starts_with	префикс
ends_with	суффикс
matches	RE2-регулярное выражение

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

curl -X POST "$NOTIFLY_URL/email-inbox/17/rules" \
     -H "Content-Type: application/json" \
     -H "X-Notifly-Key: <client-token>" \
     -d '{
       "appId": 12345,
       "name": "Критичные алёрты бэкапа",
       "filter": {
         "match": "all",
         "conditions": [
           {"field": "from", "op": "contains", "value": "@reg.ru"},
           {"field": "subject", "op": "starts_with", "value": "[ALERT]"}
         ]
       },
       "titleTemplate": "Reg.ru: {subject}",
       "messageTemplate": "{body}",
       "priority": 8,
       "position": 0
     }'

В ответе — полный объект правила с id, заполненным appName и значениями по умолчанию (enabled: true).

Пример с заголовком (header)

{
  "field": "header",
  "headerName": "X-Priority",
  "op": "equals",
  "value": "1"
}

Шаг 2 (быстрый). Правило из примера письма (AI)

Если вы уже включили saveEvents, не нужно вручную сочинять фильтр: пошлите тестовое письмо, найдите его в истории и попросите Notifly предложить правило по этому образцу — POST /email-inbox/rule/from-event/:eid.

# Без prompt — эвристика: домен отправителя + ключевое слово из темы (без LLM).
curl -X POST "$NOTIFLY_URL/email-inbox/rule/from-event/981" \
     -H "X-Notifly-Key: <client-token>"

# С prompt — подбор фильтра и шаблонов с помощью AI (списывает 1 AI-запрос из квоты).
curl -X POST "$NOTIFLY_URL/email-inbox/rule/from-event/981" \
     -H "Content-Type: application/json" \
     -H "X-Notifly-Key: <client-token>" \
     -d '{"prompt": "лови только письма про сбой репликации, заголовок — кратко"}'

Ответ — черновик {filter, titleTemplate, messageTemplate}: его нужно дополнить полем appId и отправить в POST /email-inbox/:id/rules.

Когда доступен AI-подбор

Вариант с prompt требует настроенного OPENAI_API_KEY на сервере — иначе вернётся 503. Вариант без prompt работает всегда (чистая эвристика).

История входящих (saveEvents)

Если у ящика saveEvents: true, каждое входящее письмо сохраняется как EmailInboxEvent: from, to, subject, bodyRaw, заголовки, а также status (matched / unmatched / error), matchedRuleIds и createdMessageIds. Это нужно для аудита («почему письмо не дошло?») и для подбора правил из примера.

# Список писем; фильтры: q, status, inbox_id, from, to (RFC3339), limit, cursor.
curl "$NOTIFLY_URL/email-inbox/event?inbox_id=17&status=unmatched&limit=50" \
     -H "X-Notifly-Key: <client-token>"

# Одно письмо целиком.
curl "$NOTIFLY_URL/email-inbox/event/981" -H "X-Notifly-Key: <client-token>"

# Удалить запись из истории.
curl -X DELETE "$NOTIFLY_URL/email-inbox/event/981" -H "X-Notifly-Key: <client-token>"

Диагностика «письмо не пришло»

Включите saveEvents, пошлите тестовое письмо и посмотрите status события: unmatched — ни одно правило не совпало (проверьте фильтры), error — ошибка обработки (см. поле error), matched — уведомления созданы (см. createdMessageIds).

Отправка письма

Любой SMTP-клиент шлёт письмо на полученный адрес — никаких заголовков авторизации не нужно (alias сам и есть секрет):

# msmtp / mailx
echo "База за ночь не обновилась — проверьте репликацию." \
  | mail -s "[ALERT] backups: lag > 24h" \
         "a3f9c21b8e04@in.notifly.ru"

Из Python:

import smtplib
from email.message import EmailMessage

msg = EmailMessage()
msg["To"]      = "a3f9c21b8e04@in.notifly.ru"
msg["From"]    = "alerts@example.com"
msg["Subject"] = "[ALERT] backups: lag > 24h"
msg.set_content("База за ночь не обновилась — проверьте репликацию.")

with smtplib.SMTP("smtp.example.com", 587) as s:
    s.starttls()
    s.login("user", "pass")
    s.send_message(msg)

Что попадёт в уведомление

Поле уведомления	Откуда берётся
title	titleTemplate правила; если пуст — тема письма (Subject:)
message	messageTemplate правила; если пуст — текстовое тело письма
priority	priority правила
канал	appId правила

HTML-часть, если есть, отбрасывается: уведомление — это короткий plain-text.

REST API

Метод и путь	Авторизация	Назначение
GET /email-inbox	client-token	список ящиков (с правилами)
POST /email-inbox	client-token (write)	создать ящик {name, saveEvents}
PUT /email-inbox/:id	client-token (write)	изменить {name, saveEvents}
DELETE /email-inbox/:id	client-token (write)	удалить ящик
GET /email-inbox/:id/rules	client-token	список правил ящика
POST /email-inbox/:id/rules	client-token (write)	создать правило
PUT /email-inbox/:id/rules/:rid	client-token (write)	изменить правило
DELETE /email-inbox/:id/rules/:rid	client-token (write)	удалить правило
GET /email-inbox/event	client-token	история входящих (с фильтрами)
GET /email-inbox/event/:eid	client-token	одно письмо
DELETE /email-inbox/event/:eid	client-token	удалить запись истории
POST /email-inbox/rule/from-event/:eid	client-token	предложить правило по образцу (AI)

POST /email-inbox всегда возвращает полный объект EmailInbox, включая публичный emailAddress (его удобно сразу копировать в настройки внешней системы). POST/PUT правил возвращают полный объект EmailInboxRule с appName.

Как сменить адрес?

Адрес генерируется автоматически и неизменяем. Если адрес «утёк» — удалите ящик и создайте новый: alias будет другим, старые письма на старый адрес после удаления отбрасываются.

Ограничения

• Только plain-text — HTML-вёрстка пропускается, аттачменты не сохраняются.
• Размер письма — в пределах лимитов Yandex Cloud Mail Trigger; тело в истории может быть усечено (bodyTruncated: true).
• Без правил письма отбрасываются молча — добавьте хотя бы одно правило с пустым фильтром, чтобы ловить всё.
• AI-подбор правила с prompt списывает один AI-запрос из дневной квоты и требует настроенного OPENAI_API_KEY на сервере.