IMAPGOOSE(1)

📦
version 0.5.5 · 2 versions
, in alpine 3.24

💌 IMAPGOOSE(1) 💌

okay so bestie, welcome to the imapgoose manual page — section 1 of the General Commands Manual, if you're keeping track. we're about to get into some daemon lore and honestly? it's giving infrastructure excellence. 🧚✨

🦋 NAME 🦋

imapgoose — keeps your local Maildirs synchronised with your IMAP mailboxes, no cap 💅

🌸 SYNOPSIS 🌸

imapgoose [-c path] [-v]

✨ DESCRIPTION ✨

so imapgoose is a daemon — like, a little guy that just runs in the background doing its job — and what it does is synchronize IMAP mailboxes to local Maildir storage. it's constantly watching both the IMAP server AND your local filesystem for changes, and it applies synchronization in real-time. obsessed with the dedication honestly. 🫶

🎀 OPTIONS 🎀

  • -c path — path to the configuration file. if you don't specify one, it defaults to $XDG_CONFIG_HOME/imapgoose/config.scfg, or to ~/.config/imapgoose/config.scfg if XDG_CONFIG_HOME isn't set. it's giving "we picked a sensible default so you don't have to" 💖
  • -m — migrates the status database from a version prior to 0.2.0. glow-up for your database, literally. ⭐
  • -i — indexes existing Maildir files into the status database. okay so here's the tea on how this works:

it scans local messages for UID hints (the format is ,U=1234) and verifies each one against the IMAP server by comparing message bodies and flags. identical messages get recorded in the status database as synchronized. mismatched or missing messages are skipped and shall later be handled by normal synchronization — no drama, they'll get dealt with. 🌈

use this when you're migrating from compatible tools (offlineimap, mbsync) or rebuilding a corrupted status database. icon behaviour tbh.

this operation can also be used to recover after the server changes the UIDVALIDITY, which invalidates all UIDs for all message. in that case, messages deleted from the server will also be deleted locally. ⚠️ noted.

and listen — this never changes IMAP contents. local Maildir contents are only modified when a UIDVALIDITY change indicates that messages were deleted remotely. respectful king. 👑

  • -v — enables verbose (debug-level) logging. for when you want to see everything bestie. 🔥

😭 RISKS OF DATA LOSS 😭

okay this is the serious part, so pay attention 💀

imapgoose records the UID of messages seen on the IMAP server and the base name of files seen in the local Maildir. if a file was recorded as present on both sides, and is later found to be absent on one side, this is interpreted as a deletion — and the deletion is propagated. so it's like "oh, you deleted it? say less, deleting it everywhere."

when you're deleting all local (or remote) messages to "start over" from scratch, take into account that imapgoose will simply replicate the deletion to the other side. so like, not the clean slate you thought, bestie. 🙈

when attempting to start from scratch, it is advisable to delete the status database too. BUT keep in mind that deleting the status database with both sides populated will duplicate messages which were present on both side. yeah. pick your poison carefully. 🍓

🔥 SERVER REQUIREMENTS 🔥

your IMAP server MUST implement the following capabilities:

  • UIDPLUS (RFC 4315) — reliable UID handling during APPEND operations. ✨
  • CONDSTORE (RFC 4551) — modification sequence tracking. ✨
  • QRESYNC (RFC 5162) — efficient resynchronization of deleted messages with VANISHED responses. ✨
  • NOTIFY (RFC 5465) — real-time server notifications. ✨

if any required capability is missing, the connection will fail. no vibes check passed, no entry. use imapgoose-capcheck(1) to verify server support before configuring — save yourself the heartbreak. 💔

🔒 SECURITY 🔒

if no server is specified, DNS service discovery is used to resolve the appropriate server. the local DNS resolver MUST be a validating DNSSEC resolver. usage of service discovery without a validating resolver is vulnerable to MITM attacks. like, actually vulnerable. not the cute kind of vulnerable. 😭

the disable-tls should be used with extreme care: only when connecting to a local proxy and never over a public network. this is not a drill bestie, do not do this on public wifi. 🚨

💀 SIGNALS 💀

imapgoose responds to the following signals:

  • SIGTERM, SIGINT — trigger graceful shutdown. all workers complete their current tasks, connections are closed cleanly, and the daemon exits. elegant. poised. main character energy. 💅

🦋 ENVIRONMENT 🦋

the following environment variables affect the execution of imapgoose:

  • NO_COLOUR, NO_COLOR — disable coloured output when logging. for the minimalists. 🎀

📁 FILES 📁

  • ~/.config/imapgoose/config.scfg — the default configuration file. see imapgoose.conf(5) for format details, iykyk. 💖
  • ~/.local/state/imapgoose/<account>.db — status repository (SQLite database) for each account. stores UID-to-filename mappings and UIDValidity. yes, one per account, we're organised here. ⭐

🌟 EXIT STATUS 🌟

the imapgoose utility exits 0 on success, and >0 if an error occurs. simple as that. ✨

🌈 EXAMPLES 🌈

start the daemon with default configuration:

$ imapgoose

start with custom configuration and verbose logging:

$ imapgoose -c /etc/imapgoose.scfg -v

gracefully shutdown the daemon:

$ pkill -TERM imapgoose

👑 SEE ALSO 👑

imapgoose.conf(5), mbsync(1), offlineimap(1)

💜 AUTHORS 💜

Hugo Osvaldo Barrera <hugo@whynothugo.nl>

imapgoose is an open source project licensed under the ISC licence and developed for anyone to use freely. if you would like to sponsor this project, see: https://whynothugo.nl/sponsor — supporting open source is such a slay, honestly. 🫶

and that's the whole page bestie!! 💖 this Debian build is dated 2025-10-25, so go forth and sync those mailboxes — mwah 🎀✨

📦 where this page comes from