Email Inbox (receiving emails as notifications)

Email Inbox is a “mailbox” that uses Notifly channels instead of your IMAP. When you create an inbox, you get a unique email address like <alias>@in.notifly.ru. Everything sent to it is processed by routing rules: each rule checks a filter to decide which channel to send a notification to and with what title/text.

This is convenient when an external system only knows how to send email and teaching it to use HTTP is too expensive:

• alerts from hosting providers, billing systems, RBLs and registrars;
• notifications from CI/CD, backup systems, third-party SaaS;
• transactional email from your own backend (orders, registrations) without a separate push channel;
• alerts from legacy hardware monitoring systems that only support SMTP.

Two setup steps

The inbox itself is not bound to a channel — it only accepts mail. Routing is performed by separate rules. So setup consists of two steps:

1. Create an inbox → get the address <alias>@in.notifly.ru and put it into the external service settings.
2. Add a rule (or several) → specify a filter (when the rule should trigger) and the recipient channel.

If the inbox has no rules, an incoming email is silently discarded (no notifications are produced). Emails are checked against rules in ascending position; for each matching rule a notification is created in its channel.

How it works

SMTP sender ──► <alias>@in.notifly.ru
                     │
                     ▼
              Yandex Cloud Mail Trigger
                     │
                     ▼
        Cloud Function notifly-email
                     │  1. extract alias from the address
                     │  2. find EmailInbox by alias
                     │  3. run the email through the inbox rules (by position)
                     │  4. for each matching rule — title/message by template
                     ▼
       INSERT messages + push into WebSocket (for each matching rule)
                     │
                     ▼
        All your clients receive the notifications

• Routing — by the alias in the local part of the address.
• Push — same as a regular POST /message: an immediate frame via WebSocket plus a DB record for subsequent GET /message.
• Optionally incoming emails are saved in the history (see saveEvents below).

Step 1. Creating an inbox

Via the admin UI

1. Open app.notifly.ru → Email Inbox.
2. Click “Create inbox”, fill in:
   • Name — display name, e.g. “Reg.ru Alerts”.
   • Save incoming — whether to store email texts in history (saveEvents).
3. The generated email address will appear on the card — this is the authentication. Copy it to the external service settings.

Via the REST API

Request body — EmailInboxParams: {name, saveEvents}. The inbox does not have an appId — the channel is assigned by rules.

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

The response will contain the inbox object with emailAddress filled:

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

alias is 12 hex characters, generated automatically and immutable.

Via MCP (for an AI assistant)

If you have Notifly MCP server set up, just ask:

Create an Email Inbox named “Алёрты Reg.ru” and a rule that sends to the “Operations” channel emails where from contains @reg.ru. Send the address.

Step 2. Routing rules

A rule (EmailInboxRule) describes which emails to catch and where to send them. A rule has:

Field	Purpose
appId	recipient channel (required)
name	rule name for display
filter	trigger conditions (see below); empty filter = “always matches”
titleTemplate	notification title template; empty → email subject
messageTemplate	notification message template; empty → email body
priority	notification priority
enabled	whether the rule is enabled (defaults to true)
position	evaluation order (ascending)

In titleTemplate / messageTemplate templates the following placeholders are available: {subject}, {body}, {from}, {to}, {date}, {alias}.

Filter

filter (EmailFilter) is a match plus a list of conditions:

• match: "all" — all conditions must be met (AND, default);
• match: "any" — at least one condition must be met (OR);
• empty conditions means “always matches” (default rule).

Each condition (EmailFilterCondition) has field, op, value (and caseSensitive, default false).

Fields (field):

field	What it checks
from	From header (address or name)
to	To header (address)
subject	email subject
body	email plain-text body
header	arbitrary header (name in headerName)

Operators (op):

op	Meaning
contains	substring
not_contains	absence of substring
equals	exact match
not_equals	exact mismatch
starts_with	prefix
ends_with	suffix
matches	RE2 regular expression

Creating a rule

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
     }'

The response is the full rule object with id, filled appName and default values (enabled: true).

Header example (header)

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

Step 2 (quick). Rule from an example email (AI)

If you already enabled saveEvents, you don’t need to craft the filter manually: send a test email, find it in the history and ask Notifly to suggest a rule based on that example — POST /email-inbox/rule/from-event/:eid.

# Without prompt — heuristic: sender domain + a keyword from the subject (no LLM).
curl -X POST "$NOTIFLY_URL/email-inbox/rule/from-event/981" \
     -H "X-Notifly-Key: <client-token>"

# With prompt — pick filter and templates using AI (consumes 1 AI request from quota).
curl -X POST "$NOTIFLY_URL/email-inbox/rule/from-event/981" \
     -H "Content-Type: application/json" \
     -H "X-Notifly-Key: <client-token>" \
     -d '{"prompt": "catch only emails about replication failure, title — concise"}'

The response is a draft {filter, titleTemplate, messageTemplate}: you need to add appId and send it to POST /email-inbox/:id/rules.

When AI-based selection is available

The variant with prompt requires OPENAI_API_KEY configured on the server — otherwise it returns 503. The variant without prompt always works (pure heuristic).

Incoming history (saveEvents)

If an inbox has saveEvents: true, every incoming email is saved as an EmailInboxEvent: from, to, subject, bodyRaw, headers, and also status (matched / unmatched / error), matchedRuleIds and createdMessageIds. This is useful for audit (“why didn’t the email arrive?”) and for generating rules from an example.

# List emails; filters: 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>"

# Single email in full.
curl "$NOTIFLY_URL/email-inbox/event/981" -H "X-Notifly-Key: <client-token>"

# Delete an entry from history.
curl -X DELETE "$NOTIFLY_URL/email-inbox/event/981" -H "X-Notifly-Key: <client-token>"

Diagnosis for “email didn't arrive”

Enable saveEvents, send a test email and check the event status: unmatched — no rule matched (check your filters), error — processing error (see the error field), matched — notifications were created (see createdMessageIds).

Sending an email

Any SMTP client sends an email to the provided address — no authorization headers are needed (alias itself is the secret):

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

From 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)

What will be in the notification

Notification field	Where it comes from
title	rule’s titleTemplate; if empty — email subject (Subject:)
message	rule’s messageTemplate; if empty — email plain-text body
priority	rule’s priority
channel	rule’s appId

HTML part, if present, is discarded: a notification is short plain-text.

REST API

Method & path	Authorization	Purpose
GET /email-inbox	client-token	list inboxes (with rules)
POST /email-inbox	client-token (write)	create an inbox {name, saveEvents}
PUT /email-inbox/:id	client-token (write)	update {name, saveEvents}
DELETE /email-inbox/:id	client-token (write)	delete an inbox
GET /email-inbox/:id/rules	client-token	list inbox rules
POST /email-inbox/:id/rules	client-token (write)	create a rule
PUT /email-inbox/:id/rules/:rid	client-token (write)	update a rule
DELETE /email-inbox/:id/rules/:rid	client-token (write)	delete a rule
GET /email-inbox/event	client-token	incoming history (with filters)
GET /email-inbox/event/:eid	client-token	single email
DELETE /email-inbox/event/:eid	client-token (write)	delete history entry
POST /email-inbox/rule/from-event/:eid	client-token	suggest a rule from an example (AI)

POST /email-inbox always returns the full EmailInbox object, including the public emailAddress (convenient to copy immediately to the external system settings). POST/PUT rules return the full EmailInboxRule object with appName.

How to change the address?

The address is generated automatically and is immutable. If the address “leaked” — delete the inbox and create a new one: the alias will be different, and old emails to the old address are discarded after deletion.

Limitations

• Plain-text only — HTML layout is ignored, attachments are not saved.
• Email size — within Yandex Cloud Mail Trigger limits; body in history may be truncated (bodyTruncated: true).
• Without rules emails are silently discarded — add at least one rule with an empty filter to catch everything.
• AI-based rule generation with prompt consumes one AI request from the daily quota and requires OPENAI_API_KEY configured on the server.