mailcellar
Gmail full? Keep every email on your own disk, and free the space.
Your mail lives on someone else's server, in a mailbox with a size limit.
When it fills up you can pay for more storage, or delete mail you may need
later. mailcellar gives you a third way: a complete, checked backup on your
own disk, then old mail taken out of the mailbox by rules you write and
review, still searchable and restorable whenever you need it. It works
with Gmail and Google Workspace, and with any IMAP mailbox: iCloud Mail,
Yahoo Mail, Fastmail, or your own server.
Why mailcellar
- Your storage is full. Offload old mail by rule (older than five
years, newsletters, large attachments) and keep it in the backup: the
space comes back and nothing is lost.
- You have no backup of your own. Providers keep your mail safe from
their own failures, not from a deletion, a compromised account, or being
locked out. A provider's export copies everything again each time, with
nothing to say it's complete. mailcellar fetches only what changed,
compares each account with its backup (
count) and checks the files
(verify).
- Old mail must stay findable.
search covers every backup, offloaded
mail included, and restore puts back one message, a batch or a whole
account.
- Your mail is with more than one provider. One backup, one search and
one set of reports cover Gmail and IMAP accounts side by side.
- You're moving to another provider.
restore --to copies mail from
one account to another, Gmail to IMAP or back: labels become folders and
folders labels, and the backup records what moved.
What it does
- Back up every account incrementally, in
Got Your Back's format; an
existing gyb backup carries on where it is.
- Offload old mail by rule, in stages you check: plan, review, mark,
look in your mail client, then trash. The backup is checked for every
message before it goes, and nothing is ever deleted permanently.
- Find and restore: search the backups, offloaded mail included, and
put mail back into the same account or another.
- Deduplicate, export and report: remove duplicate copies within and
across accounts, copy mail out as an mbox or a zip, and see what takes up
the space.
- Keep mail as it is: a hash chain shows the backup hasn't changed
since each message was saved (
verify --chain), and a legal hold keeps
the mail a dispute or an audit needs out of reach of offloading, pruning
and dedup, in the mailbox and in the backup.
What changes your mailbox. Only offload apply, dedup apply and
restore --yes, and each is a dry run until you add a flag. Offload and
dedup mark mail for review, then move it to Trash: nothing is ever
permanently deleted, and Gmail keeps Trash for 30 days. On an IMAP server
this happens only where the server can move mail safely; elsewhere
mailcellar backs up only. restore only puts mail back: out of Trash, or
as an upload. Everything else, backup included, only reads
(details).
Your mail stays yours. mailcellar runs on your own computer: there is
no service in between, and your mail goes nowhere but between the mailbox
and your disk. Gmail is read through your own Google Cloud project (about
ten minutes to set up,
guide); an
IMAP account needs only its password (an app password, where the provider
asks for one). mailcellar is in beta: it is used
on real mailboxes, and its backups are in gyb's fixed format, but commands
and options may still change before 1.0. It runs on macOS and Linux and
needs Python 3.14, which uv installs for you.
Not the Mac app of the same name. mailcellar is free and open source,
installed from PyPI, with no paid edition and nothing else to download. A
paid macOS app sold as "Mailcellar" on newmac.app is unrelated to this
project
(how to tell).
Commands
mailcellar setup [ADDRESS] add a Gmail account (OAuth client) or an IMAP one (--imap)
mailcellar backup [ACCOUNT ...] incremental backups in gyb's format
mailcellar count [ACCOUNT ...] compare the mailbox with the backup
mailcellar meta [ACCOUNT ...] fill the per-message sidecar for older mail
mailcellar verify [ACCOUNT ...] check that the backup's files are still intact
mailcellar schedule install|status|remove run backups regularly, unattended
mailcellar dedup … find duplicates and remove them from the mailbox, in stages
mailcellar offload … take old mail out of the mailbox, keeping it in the backup
mailcellar restore ACCOUNT … put backed-up mail back, into its account or another
mailcellar export ACCOUNT … copy mail out as an mbox file or a zip of .eml files
mailcellar search QUERY … find mail in the backups, offloaded mail included
mailcellar hold add|list|show|release keep mail for a dispute or an audit
mailcellar report … storage, bulk mail, volume, threads, labels, correspondents,
backup health, top senders
mailcellar config where the config and data live; each account's state
backup, count and meta take every configured account unless given
some (an address, a config name like work, or a unique part of an
address). Each command takes --help.
Results go to stdout; progress, warnings and errors go to stderr. Add -v
anywhere on the line to also see the server's retries and rate-limit waits
(waits of 10 seconds or more show without it), or -q to see only warnings
and errors.
How it fits together: How it works.
Quick start
You need uv (it provides Python 3.14).
-
Install.
uv tool install mailcellar # from PyPI; puts the mailcellar command on your PATH
pipx install mailcellar works too, with Python 3.14. To run it from a
clone instead, see Development.
-
Add an account, one of these two ways.
Gmail or Google Workspace. Create an OAuth client in the
Google Cloud console: a project with
the Gmail API enabled, a consent screen with yourself as a test user,
and an OAuth client of type Desktop app. Download its JSON. The step
by step version, including Testing versus In production (Testing
tokens expire after 7 days), is
Setting up Google Cloud.
Then:
mailcellar setup [email protected] --client ~/Downloads/client_secret_*.json
Any other mailbox, over IMAP (iCloud Mail, Yahoo Mail, Fastmail, your
own server). Most providers want an app password, made in their account
settings; give setup the server, and it asks for the password:
mailcellar setup [email protected] --imap imap.mail.yahoo.com
| Provider | Server | Note |
|---|
| iCloud Mail | imap.mail.me.com | --username with the part before @; backup only (no IMAP MOVE) |
| Yahoo Mail | imap.mail.yahoo.com | add --review folder to offload: Yahoo keeps no custom keywords |
| Fastmail | imap.fastmail.com | not yet tried with mailcellar |
More in Backing up an IMAP account.
Either way, setup signs in read-only, changes nothing in the mailbox,
and names the account after the address (alex; chooses
another). The backups go in ; to keep them elsewhere, set
in
().
Then keep the backup safe, and when you are ready
to free space, offload old mail.
Documentation
The documentation site has the guides and the reference.
Guides, in the order you will want them:
- Setting up Google Cloud: the project and OAuth
client mailcellar signs in with, and the first consent screen.
- Backing up an IMAP account: back up
mail on another provider's server, or your own; offload, dedup and restore
there too, where the server can move mail safely.
- Workspace: backing up through a service account:
unattended, read-only backups of a domain's mailboxes without each person signing in.
- Backing up, and keeping the backup safe: the
routine, a second copy of the data root and checking it,
backup --prune.
- Scheduled backups: run backups unattended, and
what happens when a token needs signing in.
- Migrating from gyb: continue an existing Got Your
Back backup.
- Finding mail, and deciding what to offload:
search, and which report answers what.
- Offloading old mail safely: a worked example,
from writing a rule to restoring.
- Removing duplicate mail: a worked example, from
matching to trashing.
- Restoring mail: undo an offload, recover one
message, rebuild or copy an account, load a Takeout file.
- Exporting mail: copy mail out as an mbox or a zip.
Command reference, every command and option:
- Backups:
backup, count, meta, verify
- Configuration: the config folder,
accounts.toml, settings.toml; setup, auth, schedule, config
- What changes your mailbox: the commands that write to Gmail, or to an IMAP server
- Removing duplicates:
dedup
- Offloading old mail:
offload, and the rule keys
- Restoring mail:
restore
- Exporting mail:
export
- Searching mail:
search
- Reports:
report
Development
To run mailcellar from a clone, with the tests and tools:
git clone https://github.com/mailcellar/mailcellar.git
cd mailcellar
uv sync # the dependencies, and mailcellar in editable mode
uv run mailcellar config # every command, run from the clone
uv run pytest # all tests; no network, never the real config or data
uv run pytest --cov # the same, with a branch-coverage report
uv run ruff format && uv run ruff check
The code is one package, src/mailcellar/: cli.py dispatches to
backup/, dedup/, offload/, restore/ and report/, which share paths.py,
gmailapi.py and message.py. uv sync installs it in editable mode;
python -m mailcellar works too. See
How it works.
How to contribute, and the rules changes follow:
CONTRIBUTING.md.
Acknowledgements
mailcellar's backups use the on-disk format of
Got Your Back (gyb) by the
GAM team, so backups made by either tool can be read by the other.
mailcellar is a separate project and shares no code with gyb.
mailcellar is not affiliated with or endorsed by Google or the gyb
project. Gmail and Google Workspace are trademarks of Google LLC.
License
Apache License 2.0: see LICENSE and NOTICE.
