-
-
Notifications
You must be signed in to change notification settings - Fork 0
Mail Rules
Since IRIS-NG-v2.0.0, a mailbox can be an alert source: IRIS-NG polls IMAP on a fixed
interval and turns messages into alerts according to rules you define. Mail uses the
Python standard library only — no new dependency, no external service.
Validation status. Mail ingestion has been exercised end to end against test messages, but had not yet been run against a live IMAP/SMTP server at release. If you are the first to point it at a real mailbox, start with a low-volume one and watch the ingest log.
Configuration is split across two pages, on purpose:
- Server settings → Mail — the IMAP and SMTP connection settings, with Test IMAP / Test SMTP buttons and Poll now.
- Settings → Mail rules — the rules themselves and the ingest log.
Mail passwords are write-only, end to end. They are stored and used, but never returned by the API and never pre-filled into the form. The page tells you whether a password is set, not what it is; leaving the field empty on save keeps the stored value.
The poller runs on a fixed 60-second tick and gates itself on the settings — if mail is unconfigured or disabled, the tick does nothing. Only one poll runs at a time, even with several workers, so a slow mailbox cannot pile up concurrent fetches.
Two properties keep it from ever wedging:
- Nothing loops. A message that cannot be parsed is recorded in the ingest log and marked seen, rather than being retried forever.
- Rules fail closed. A bad regular expression or an unknown field matches nothing, not everything. A broken rule can miss mail; it cannot flood the alert queue.
Rules are ordered, and first match wins. Each rule is:
- Conditions — regular expressions over the subject, sender, recipient or body, AND-ed together. A message must satisfy all of a rule's conditions to match it.
- An action — create an alert or ignore. Ignore rules exist so vendor digests and auto-replies can be silenced explicitly, without reaching the alert queue and without disappearing silently — an ignored message is still logged as ignored.
- Alert defaults for create rules — customer, severity, classification, source, and a title template.
Order matters exactly the way you would expect: put narrow, specific rules above broad ones, and ignore rules above the create rules they should shield.
Every polled message gets a log entry regardless of outcome: created an alert, matched an ignore rule, matched nothing, was a duplicate, or errored — with the rule that matched and, where AI triage ran, what the model suggested. The log is how you tune rules against real traffic: run Poll now, read what happened, adjust, repeat.
If an AI backend is configured (AI Features), a create rule can hand the message to AI triage before the alert is written. Triage may:
- refine the rule's default severity and classification — validated by name against your live catalogs, so the model cannot invent a category; and
- extract indicators from the body, at a stricter confidence bar than the note-extraction flow, since no analyst reviews them before they land on the alert.
It is strictly advisory. If the backend is down, slow, or unsure, the rule's own defaults apply and the alert is created regardless — mail flow never depends on a model. What the model suggested (and whether it was applied) is recorded on the ingest log entry, so every AI-touched alert is auditable after the fact.
- Alerts created from mail enter the normal pipeline: clustering rules and investigation flows apply to them like any other alert, and they can be escalated, merged and clustered normally.
- Email delivery of notifications is a separate feature with its own switch — see Notifications. It shares the SMTP settings.
- There is no per-rule schedule; the poller is one loop over one mailbox at the fixed interval.
| Symptom | Likely cause |
|---|---|
| Test IMAP fails, settings look right | Wrong port/TLS combination, or the provider requires an app-specific password |
| Messages arrive but no alerts | No create rule matched — check the ingest log's matched nothing entries and loosen conditions |
| A rule that should match doesn't | Regular expression error — rules fail closed, so a bad pattern matches nothing. Test the regex outside first |
| The same mail keeps being ignored | An ignore rule above it matches first — rules are ordered, first match wins |
| Alerts have the rule's default severity despite AI triage | The backend was unavailable or unsure — the log entry records what happened |