Notifications are usually the last thing discussed when a company builds an internal tool. The screens work, the data is correct, and then someone says: "It should send an e-mail when something happens." A developer adds a message for every event, and within a month people have a rule in their mailbox that moves everything from the tool into a folder nobody opens.
The result is worse than no notifications. The one message that mattered, an approval waiting for three days, sits among forty that did not. This article gives a simple way to decide what the tool should send before anyone writes the code.
Start from the action, not the event
An event is something that happens in the tool: a record is created, a status changes, a file is uploaded. A notification is worth sending only when a specific person has to act or would be hurt by not knowing. Those are different things, and most unwanted e-mail comes from treating them as the same.
For each candidate message, ask three questions:
- Who has to do something because of this? If the answer is "nobody, but it is good to know," it is not an urgent e-mail.
- What exactly should they do? If you cannot name the action, the message will not make anyone act.
- What happens if they do not? If the answer is "nothing," drop the message or move it into a digest.
A table for every message
Before development, write one row per message. A spreadsheet is enough.
| Message | Trigger | Recipient | Action | If ignored |
|---|---|---|---|---|
| Approval requested | A request is submitted | The named approver | Approve or reject in the tool | Reminder after two working days, then the approver's manager |
| Request approved | The approver decides | The person who submitted it | Continue the work | Nothing breaks; the status is visible in the tool |
| Import failed | A scheduled import ends with errors | The tool owner | Check the import log | Data in the tool becomes out of date |
| Weekly summary | Every Monday morning | Team lead | Read; no action needed | Nothing |
The last column matters most. It tells you which messages are critical and which are only convenient. The first and third rows are critical. The second and fourth can be turned off without harm.
Choose the recipient carefully
Sending to a shared address or a whole team feels safe, but it spreads responsibility until nobody feels it. Prefer a named person, with a named backup for holidays. If a role is responsible, such as "whoever is on duty this week," let the tool look up the current person rather than using a fixed list.
Avoid copying managers by default. A manager who receives every message learns to skim them, and then misses the escalation that was meant for them. Escalate to a manager only after a stated delay, as in the table above.
Digest or immediate?
Immediate e-mail suits messages that need action within hours. Everything else can wait for a digest: one message per day or per week that lists what happened. Typical digest candidates are status changes on records someone follows, new comments and routine completed tasks.
A good digest is short, sorted by what needs attention first and links to the tool for details. If it is long every day, it has the same problem as many single messages, and the list of what goes into it needs trimming.
Let people tune what they receive
Different people care about different things. Offer a simple setting, for example "e-mail me about my own requests" and "e-mail me about my team's requests," and keep it to a handful of options. Do not allow the critical messages from the table to be switched off by the recipient; those belong to the process, not to personal taste.
Write the message so it can be acted on
A short, consistent message is easier to handle than a long one. Put the action in the subject line, for example "Approval needed: travel request from J. Novak, due Friday." In the body, give one sentence of context, one clear link to the exact record and the deadline. Do not include sensitive data in the text; a link that requires sign-in is safer than a copy of the content. Our article on error messages in an internal tool uses the same principle for what appears on screen.
Send from an address that people recognise and that is set up so the messages are not filtered as spam. If your company uses its own domain, ask whoever manages your mail to confirm that the tool's sending is authorised.
Check what happens in practice
After launch, look at what the messages do. For two or three weeks, note which ones led to an action within a day and which were never opened or acted on. If the tool keeps a log of what it sent, as described in what to log in a small internal tool, this is a quick count rather than a guess.
Then cut. Remove messages nobody acted on, or move them to the digest. Do this again every quarter, because tools grow and every new feature tends to bring a new message. When you add a notification, tell people in the release notes so it does not come as a surprise.
Common mistakes
- One message per event. The default in most tools; it produces volume, not information.
- Sending to the whole team. Everyone assumes someone else will act.
- No reminder or escalation. A critical message with no follow-up depends on luck.
- Details in the e-mail body. Personal or commercial data copied into mailboxes is hard to control.
- Never reviewing. The list only grows.
A first step
Take the notifications your tool sends today, or the ones planned, and fill in the five-column table. Mark each message critical or convenient. Turn convenient ones into a daily digest, and agree who reviews the table in three months.
Sources
- Google Site Reliability Engineering, Monitoring Distributed Systems (alerts should be actionable and mean that a human needs to do something)
- Google Site Reliability Engineering, Being On-Call (the cost of too many alerts)
- This article is a planning aid. The examples are generic and the names are invented. No client results or performance figures are claimed.