Keeping Offline Mail Sync Honest About OAuth Tokens
My mail setup is deliberately old-fashioned: offlineimap pulls everything down into local Maildirs, mutt reads it, msmtp sends it, and none of it touches a browser. It covers half a dozen accounts across Gmail, Outlook, Yahoo, and a couple of accounts on my own domains. It had been working fine for months, right up until I noticed one account, the Outlook one, quietly failing to sync while everything else kept going.
A Token That Only Refreshes When It’s Already Stale
The mail accounts that need OAuth2 go through a small token manager I run alongside offlineimap, and its normal mode is lazy: ask it for a token, and it hands you the cached one unless that token has already gone stale, in which case it refreshes first. That’s a sensible default for an interactive tool, but it means the token only ever gets renewed at the exact moment something is trying to use it. If a sync run hits a provider having a bad day right at that renewal moment, the whole account’s sync fails for that cycle, and it has to wait for the next cycle to try again.
A Timer, Not an Afterthought
The fix wasn’t to make the lazy refresh smarter, it was to stop relying on it being triggered at the right moment at all. I wrote a small script that unconditionally refreshes every OAuth account’s token, logs the result, and exits, then wired it up as its own systemd timer running every twenty minutes, independent of whenever offlineimap itself happens to run. Tokens now get renewed on a steady clock rather than on-demand, so by the time offlineimap actually needs one, it’s almost never the thing standing in the way.
The one gotcha worth remembering: a systemd timer’s OnUnitActiveSec measures time since the service last finished, which resets to “never” on every reboot unless you also set OnBootSec. Forget that pairing and the timer will sit there doing nothing until some other event happens to trigger it, which is a quietly confusing way to lose faith in a fix that was actually working fine.
The Part That Wasn’t Actually the Problem
Once the proactive refresh was in, I still saw occasional Outlook failures, and for a moment I assumed the token logic still had a gap. Digging into the sync logs showed something else: Microsoft’s own servers resetting the connection mid-handshake, not an authentication failure at all. That’s outside anything a better token-refresh schedule can fix. What mattered more was confirming that offlineimap handles this the way I’d hoped: each account syncs in its own thread, so one account stuck retrying against a flaky server doesn’t stall the others. Gmail, Yahoo, and the rest kept syncing on schedule the entire time Outlook was having a bad afternoon.
Setting Up Something Similar
None of this is specific to my setup, so if you’re running offlineimap (or anything else) against OAuth2-gated mail with its own token-refresh CLI, the pieces are small enough to copy. I keep a scrubbed version of my dotfiles public at github.com/okubax/dotfiles, and the relevant bits are all there: bin/oauth-token-refresh is the script itself, and systemd/user/oauth-token-refresh.timer plus its matching .service file are the timer unit that runs it every twenty minutes. The public copy is trimmed to a single example account rather than my real list, so the only edit needed is swapping the ACCOUNTS=(gmail) line for whatever account names your own token manager actually uses, and pointing ExecStart at wherever you’ve put the script. Symlink the two unit files into ~/.config/systemd/user/ and systemctl --user enable --now oauth-token-refresh.timer and it’s running. The one thing worth reading before copying it blindly: the comment in the timer file explaining why OnBootSec=0 has to sit alongside OnUnitActiveSec, since skipping it is the easiest way to end up with a timer that looks enabled and does nothing.
Boring Infrastructure, On Purpose
None of this was a particularly dramatic fix, and that’s sort of the point of maintaining your own small infrastructure instead of trusting someone else’s app: the failure mode is visible in a plain text log instead of hidden behind a generic “something went wrong, try again later,” and the fix is a script and a timer you fully understand rather than a support ticket. It’s not glamorous work, but it’s the kind that means I’ll stop thinking about my mail setup again for a good while.