A simple script to monitor the number of unread emails in your inbox.
Optionally, you can also configure your .bashrc to show the number of unread messages when opening a terminal.
To install, simply clone this repository somewhere.
You may start the monitor with uv run:
<password_command> | uv run <install_path>/imap-watcher.py <host> <user>This will monitor your inbox by default.
You can change the watched folder with the --folder flag.
Afterwards, you can read the number of unread messages from ~/.local/state/imap-watcher (can be changed with --file).
The file is automatically (and atomically) updated instantly whenever:
- a new message is received;
- a message is marked as read or unread;
- a message is deleted or moved.
If you'd like to display the number of unread messages when opening a terminal, add this to your .bashrc (below [[ $- != *i* ]] && return):
<install_path>/banner.sh
alias imap-watcher-start='( <password_command> | uv run <install_path>/imap-watcher.py <host> <user> & disown; )'Note that imap-watcher.py will read your password from stdin.
We recommend piping the output of a password manager (e.g. pass).
You can monitor multiple email accounts simultaneously by using multiple watchers, each using a different file. For instance:
alias imap-watcher-work='( <work_password_command> | uv run <install_path>/imap-watcher.py <host_work> <user_work> --file ~/.local/state/imap-watcher-work & disown; )'
alias imap-watcher-personal='( <personal_password_command> | uv run <install_path>/imap-watcher.py <host_personal> <user_personal> --file ~/.local/state/imap-watcher-personal & disown; )'
alias imap-watcher-start='imap-watcher-work && imap-watcher-personal'You can then make a multi-account banner:
file="$HOME/.local/state/imap-watcher"
if [[ -r "$file-work" && -r "$file-personal" ]]
then
w=$(cat "$file-work")
p=$(cat "$file-personal")
echo "You have $((w + p)) unread messages ($w from work, $p<
5FF3
/span> personal)."
echo
else
# ...
fiMIT License
Copyright (c) 2026 Luiz Henrique Laurini
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.