# Notifications: alerts by email

With BoxLang+, BxLens can send you an email when something is wrong, before your users call. Fifteen alerts watch the JVM, disks, errors, traffic, databases, tasks, dependencies, mail, AI, security and the logs. Every alert is **off** until you switch it on, one by one.

Set it up in **Settings, Notifications** (admin only).

## 1. Say how mail is sent

Lens sends the mails itself over SMTP. It does not use bx-mail, so an alert can still reach you when the application, or its mail module, is the thing that is broken.

| Setting | Meaning |
|---|---|
| Server, port, security | Your SMTP server. Security is STARTTLS (port 587 usually), SSL (465) or none (a trusted relay only). TLS 1.2 and 1.3, and the server name is checked. |
| User | Empty when the relay needs no login. |
| Password | Never typed in the console. Put the **name** of an environment variable (for example `SMTP_PASSWORD`) in the field, or set `notifications.smtp.password` as a `bxsecret:` value in `boxlang.json`. The page shows where the password is found, never the password. |
| From, name, reply to | Who the mail is from. |

Press **Send test mail** to see the answer of your SMTP server in plain words.

## 2. Say who gets mail

Add people with an address and a name. For each person you choose:

- whether they get alerts at all,
- the lowest severity (warnings and critical, or critical only),
- the categories (none means all): availability, jvm, capacity, errors, traffic, database, runtime, tasks, dependencies, mail, ai, security, logs,
- which reports they get (daily, weekly, monthly), see [Email reports](email-reports.md).

At most 50 people. An address cannot carry a line break or a list of addresses.

## 3. Switch alerts on

| Alert | Fires when | Default limits |
|---|---|---|
| Server down (critical) | A server stops saving its health snapshot and heartbeat | 3 minutes |
| Deadlock (critical) | The JVM reports threads that wait for each other | |
| Heap pressure (critical) | The heap stays above a limit, or GC uses too much time | 90% for 5 minutes, or GC above 30% |
| Disk space (critical) | A volume is nearly full, or a folder Lens must write to is read only | 90% used |
| Error spike (critical) | Many errors a minute, or an error never seen before | 20 a minute over 5 minutes, new group on |
| Failed requests (critical) | The share of failed requests (a 5xx or an uncaught error) is high | 5% of at least 50 requests over 5 minutes |
| Slow site (warning) | The average response time stays high | 2000 ms for 10 minutes, at least 50 requests |
| Datasource pool (critical) | Requests wait for a database connection | 2 minutes |
| Executor saturated (warning) | An executor is critical or has a long queue | 100 queued tasks |
| Scheduled task failing (warning) | A task is failing | 2 failures |
| Outgoing HTTP (warning) | A host the app calls fails more than the [HTTP page](http.md) limit | |
| Mail (warning) | Bounces, a high failure rate, a spool that does not drain ([Mail](mail.md) integration) | |
| AI (warning) | Failed runs, rate limits, or a cost over your daily budget ([AI](ai-observability.md) integration) | budget off |
| Security (critical) | Repeated failed console logins, or a change of settings | 5 failures over 5 minutes |
| Errors in the logs (warning) | Many ERROR lines in the BoxLang logs | 10 a minute over 5 minutes |

You can change the severity, every limit, and how often a mail repeats while the alert stays true (default 60 minutes).

## How the mails are sent

- Every server evaluates its own alerts and lists them in its [health snapshot](servers.md#the-health-snapshot-and-the-servers-table).
- **One server sends for the whole cluster**: the one with the lowest id among the servers that wrote in the last two and a half minutes. All servers work out the same answer from the store, so nobody has to ask. The page says which one sends.
- An alert sends a **firing** mail once, a **reminder** every repeat time while it stays true, and a **resolved** mail when it stops.
- One mail per person carries every event of that minute that the person asked for, so a bad minute is one mail and not forty.
- At most `maxPerHour` mails an hour (30). A mail that cannot be sent is tried again after five minutes and the alert is not lost.
- **Pause 1 hour, Pause 1 day** and the main switch stop everything at once.
- The settings are saved in the Lens store, so a change on one server reaches the others. Without the store they live in memory on this server only, and the page says so.
- If the sender changes (a restart, or another server takes over) the alerts that are still true are announced once again.

A mail has a text part and an HTML part, links to the console when you set its address, and the headers `Auto-Submitted` and `X-Auto-Response-Suppress`, so autoresponders leave it alone. The text of an alert comes from Lens (numbers, names of volumes, executors and tasks, the message of a new error) and goes through the same redaction as the pages. Nothing is ever put into the HTML without escaping.

## Set it up with Lensy

Ask [Lensy](ai.md) in plain words, for example:

- "Email ops@acme.com when any disk is above 85 percent."
- "Tell me every morning at 8 how the servers did." (a recipient, the daily report, a time)
- "Alert the team when mail bounces more than ten times an hour."
- "Pause notifications for two hours."

Lensy first reads what is set (`alertRules`, `notifications`), then proposes **one change per step**: `alertRuleSet` (an alert and its limits), `recipientSet`, `recipientRemove`, `reportSchedule`, `notificationsSet`. Each one shows an **approval card** that says in words what it will do. For a recipient the card names the address and reminds you that anyone who can read that mailbox will see what is sent there. Nothing is saved until the admin clicks Approve, and a denied card changes nothing.

Lensy can pick only an alert from the catalog above and only limits inside the allowed range. It **cannot** change the SMTP server, user or password, so it can never send your alerts somewhere else, and it has no tool to write free text into a mail. It is told to use only an address that you gave it in the chat. These tools are for the admin role, BoxLang+, and are refused when the console is read only or `ai.actions` is off. See the [tool list](../reference/ai-tools.md#notifications-boxlang-admin-only).

## Safety

- Admin only. A viewer gets 403 and never sees the tab.
- Every change is audited (`notifications.*`), without the password.
- Refused when `console.readOnly` is on (the test mail is not a change).
- The SMTP address is chosen by an admin. Lens connects to it and nowhere else.

## Without BoxLang+

The tab shows what it offers and a BoxLang+ note. The server answers 403.