IMAP IDLE mail notifications for OfflineIMAP

by Sam Burnett on Nov 21, 2010

OfflineIMAP is a cool utility that syncs IMAP mailboxes to local Maildirs. It gives you local access to all your e-mail, and lets you use mail clients like Mutt without relying on their terrible IMAP support.

Unfortunately, OfflineIMAP has one shortcoming: it doesn’t notify you when you receive new mail. Technically speaking, it doesn’t support the IDLE extension for IMAP. Other mail clients (e.g., Thunderbird, Apple Mail, Outlook, etc.) have support for IDLE, but attempts to add such support to OfflineIMAP have stalled.

So, in lieu of native IMAP IDLE support for OfflineIMAP, I wrote a script that does the next best thing. opens connections to a set of IMAP servers and monitors mailboxes for new mail using IDLE; when it detects new mail, it invokes OfflineIMAP to fetch the mail. It isn’t quite as good as having native IMAP support (because invoking a fresh copy of OfflineIMAP requires opening a new TCP connection to the server), but it’s better than polling the server every two minutes for new mail.

Disclaimer: I use this script to check my mail every day and it works fine for me, but I’ve only tested it with two IMAP servers. Your mileage may vary. I implemented a very small subset of IMAP from scratch that logs in and starts an IDLE; there is a very high chance your IMAP server could cause my simple parser to fail.

Keep an eye on the script for the first few hours to make sure that it isn’t disconnecting or running OfflineIMAP too often.

Thanks to Robert Chien for the original idea.


To use, you need the following:

I haven’t packaged, so just chmod +x it and put it somewhere in your $PATH.

Configuring it

You put some account settings in ~/.idlemailrc. Here’s mine, which checks for mail in my Georgia Tech and GMail inboxes:

[account gatech]
server =
port = 993
mailboxes = INBOX
timeout = 4.5

[account gmail]
server =
port = 993
mailboxes = INBOX
timeout = 29

Some important details:

Using it

For testing, just run the script with no arguments. Try sending yourself some mail to see if the script detects it and properly executes OfflineIMAP.

For day-to-day usage, I’ve put the following line in my .xinitrc:

tmux new-session -s idlemail -d

(You need tmux for this to work.) This will start a new tmux session running, if needed. To see script output, connect to the session using tmux attach idlemail. You can obviously do something similar with screen, if you don’t want to install tmux.

Send Questions and Comments to Sam Burnett.