IMAP mailbox backup, self-hosted
By Lucas Flores, IT Systeme Flores UG. Last updated
Restow backs up any IMAP mailbox, on a mail server of your own or at a hoster, over IMAP with TLS. It runs on your own server, reads each folder incrementally, stores every message byte for byte in storage you choose and restores mail by IMAP append into the original or another IMAP account, or as .eml files in a ZIP. It signs in with a password today, in one of three modes: one shared login, one password per mailbox, or a master user. OAuth2 for IMAP sources is not implemented yet; planned. IMAP carries no calendar and no contacts. IMAP backup has been in every edition, Community included, since 0.1.0.
Setting up an IMAP source
Under the tenant's Connections, add a source of the type "IMAP mailbox". You enter the server, the port and the security, which is TLS (implicit, port 993) or STARTTLS (port 143); TLS is required for anything but development, and the option "None" is for a local test server only. You enter the account's username and password and test the connection before you save it: a failed test names the cause (the server rejected the username or password, the server temporarily refused the login, no answer in time, a failed TLS handshake, no STARTTLS on that port, a name that cannot be resolved, a refused connection). The password is sealed with the tenant key and never shown again; where the provider offers app passwords, they are the better choice.
An IMAP server has no directory to read the accounts from, so you add the accounts by hand or from a CSV file (columns login, name and email, plus an optional password) under Directory, "Add accounts". A password in the CSV is sealed at once and never stored or logged in clear text. A newly added account gets its first backup queued at once, and a backup job of the kind "Mail & SaaS" covers IMAP accounts together with mailboxes and OneDrives.
Three ways to sign in
One source uses exactly one of these modes, for all its mailboxes:
| Mode | How it works |
|---|---|
| Shared login | The default. One login and password on the source work for every mailbox under it. It fits an app password or a backup account that your provider lets open all mailboxes. |
| One password per mailbox | For hosters where every mailbox has its own password and there is no master account, such as Hetzner, IONOS or all-inkl. The source itself has no login to test: you add the mailboxes, then use "Set password" and "Test sign-in" on each one in the Directory tab. A mailbox without a working password shows as "Not protected" and is not backed up until one is set. |
| Master user |
One master account signs in as each mailbox, either in the
master*mailbox form that Dovecot uses (the separator can
be changed) or as SASL PLAIN with an authorization ID. Your IMAP server
has to support one of the two. For the SASL form Restow checks that
the server offers AUTH=PLAIN and fails loudly if it does
not, instead of quietly backing up the wrong mailbox.
|
A stored password never travels to another server than the one it was sealed for. If you change the host or the port of a source that uses one password per mailbox, Restow discards the sealed password of every mailbox at once and each shows "Not protected" until you set it again.
Which servers Restow can reach
Restow connects from its own server, for the connection test as for every
backup and restore. A tenant administrator can therefore enter public servers
only: loopback, private networks and local names (container names,
.local, .internal) are refused, when the source is
saved and when it connects. A server inside your network is a decision of the
operator: either for the whole installation with an installation setting, or
for one source by a provider administrator who saves the host, which approves
it for that source until someone else changes its host or port. Link-local addresses
(cloud metadata) are never allowed. The server also has to be reachable on the
port you enter; see
network and ports.
Microsoft 365 and Outlook.com have switched off IMAP sign-in with a username and password. Restow warns when you enter a Microsoft IMAP host and points you to a Microsoft 365 connection, which backs up the same mailboxes through Microsoft Graph (see the Microsoft 365 and IMAP backup overview).
How a backup runs
Restow lists the folders (LIST and LSUB, special folders recognised by their
SPECIAL-USE flag) and reads each folder incrementally by its UIDVALIDITY and
UIDNEXT. When a server changes the UIDVALIDITY of a folder, the folder is read
in full again, and deduplication by Message-ID and hash keeps the storage from
holding the mail twice. Each message is fetched with
BODY.PEEK[], which does not set the read flag, and saved byte for
byte as RFC 5322, with the flags kept separately and the internal date. Mail
that was deleted on the server is recognised at the next run by comparing UIDs,
and the restore points made before keep it.
A backup uses at most two connections per account, because many servers limit them. Everything is cut into chunks, deduplicated within the tenant and encrypted (AES-256-GCM, one key per tenant) before it reaches your storage. A message that the server lists but does not deliver is reported as a warning with the cause, and a failed login is named as such, with what to do.
Since 0.4.7, a login that the server refuses for now (too many connections
open for the account, an authentication backend that is down, or a response
code such as [UNAVAILABLE], [INUSE] or [LIMIT]) is no longer taken for a wrong
password. It is a transient cause, imap.server_limit, which
Restow retries by itself, and the connection test says "The server
temporarily refused the login". A download cap that the server reports on a
read ([LIMIT], [OVERQUOTA] or a quota text) is reported as
imap.server_limit too, not as a full mailbox: it fails the folder
as a whole and the next run resumes, instead of one failure per message (a
cap that the server reports without such a code or text still costs one
failure per message). Messages that were deleted or moved during the backup
are not counted as failures. A run whose connection dropped too often fails
as imap.connection_lost, also a transient cause, instead of
"The cause could not be identified".
What is backed up and what is not
- Backed up: the mail of the account's folders, with flags and dates, as the server delivers it.
- Not part of IMAP: calendar and contacts.
- Imported mail files (EML, MSG, MBOX) are no IMAP source and are never backed up: they are stored as an imported mailbox in the same format, which you browse and restore like an IMAP account (see mail import and export).
Restore
In the Restore explorer an IMAP account shows with its folders, search and mail preview. If the account is assigned to a person, it stands under that person as "Mail (IMAP)". You restore one message, a folder or a whole account:
- Original location or another IMAP account of the same tenant (the login of the target; offered to restore operators and tenant administrators). Restow appends the mail to the target folder with its original date and flags and creates the folder if it is missing.
- Download as ZIP with the mail as .eml files and a checksum list, from a link that is valid for 24 hours, or an export as EML or MBOX.
Restore never replaces an original. "Keep both" (the default) puts everything into a new folder, "Skip existing" leaves mail that is already there, found by its Message-ID, and restores only what is missing. There is no mode that overwrites: the API refuses it for an IMAP target, and nothing in the target account is ever deleted, overwritten or moved. A user with the role "user" sees and restores only their own data; an administrator who restores someone else's mail gives a reason, and the audit log records it as done on behalf of that person.
Since 0.4.7, an IMAP restore whose connection drops fails and is retried on a fresh connection, where the Message-ID check skips what was already appended, instead of ending "completed" with every remaining item failed.
Proven restorable
A restore check, set in the backup job (weekly by default), reads a random sample of messages back from the latest restore point through the restore path and compares them with the hashes recorded at backup; each account is rated in Recovery readiness next to mailboxes and machines. The release smoke run, which gates every release, backs up and restores an IMAP account and compares the mail byte for byte. See the verification page. Every new restore point is also judged for signs of ransomware, from the amount of change and from compression and deduplication; see the ransomware detection page.
Archiving an IMAP account (Business and above)
A backup is not an archive. Since 0.4.4, in Business and Service Provider, a mail job can also archive IMAP accounts. There are two ways, which can run together, and what both capture is archived once. "IMAP archiving" keeps the account in sync over IMAP and uses IMAP IDLE where the server offers it, and otherwise checks at intervals; it is near-time and not complete. "Forwarding to the archive address" lets the provider send a copy of every incoming and outgoing mail to an address of Restow (a Postfix or mailcow BCC map, a Sieve rule), which captures the mail at transport. With IDLE one connection per account stays open, and during a pass and a backup an account can use up to four at the same time; for a provider with a tight limit, set the source to "Check at intervals only". Details are on the page about how mail gets into the archive. Since 0.4.7, a message that the server refuses or does not deliver no longer holds back its folder or the whole pass: the other messages are captured, and after three passes the capture gives up on that message, which only the worker log names, not the interface. A refused folder costs only that folder for the pass, folders that a pass did not reach keep their state (older mail is no longer skipped after an interrupted pass), and a limit of the account stops the pass with its state kept. A watch that the server refuses with a NO on EXAMINE or IDLE is retried after minutes, doubling up to an hour, instead of being taken for a server without IDLE for a day. IMAP archiving was tested against a simulated IMAP server and the Dovecot of the release checks, and forwarding against the receiver itself, not against a real hoster, Postfix, mailcow or Google Workspace.
Stated limits, not hidden ones
- IMAP sources sign in with a password only. OAuth2 for IMAP sources is not implemented yet; planned. Restow does not create or ask for app passwords.
- Microsoft 365 and Outlook.com mailboxes cannot be backed up over IMAP with a password; use a Microsoft 365 connection.
- No calendar and no contacts: IMAP carries mail only.
- A tenant administrator can connect public servers only; a server in a private network needs the operator's decision.
- A mailbox without a working password, in the mode "One password per mailbox", is not backed up until one is set and tested.
- A backup uses up to two connections per account; archiving with IMAP IDLE keeps one more open. Plan these against your provider's limit.
- IMAP archiving is near-time and not complete, and it was tested against simulated services only (see above). Restow is a beta: run it beside your existing backup until you have restored from it yourself.
Editions
IMAP backup and restore are part of the Community core and therefore in every edition: Community, Business and Service Provider. The Community edition is free and has no mailbox limit. IMAP archiving and forwarded copies need Business or Service Provider. For what each edition adds, see pricing.
Frequently asked
How does Restow back up an IMAP mailbox?
It connects to the IMAP server over TLS from the Restow server and reads the folders incrementally: per folder it follows UIDVALIDITY and UIDNEXT, so a run fetches only new mail. Each message is stored byte for byte (RFC 5322), with its flags and its internal date, into the storage you choose, deduplicated and encrypted. Mail that was deleted on the server is noticed at the next run and stays in the restore points made before.
How does Restow sign in to the mailboxes?
With a password, today, in one of three modes per source: one shared login for every mailbox (the default), one password per mailbox, or one master account that signs in as each mailbox, in the Dovecot form master*mailbox or as SASL PLAIN with an authorization ID. OAuth2 for IMAP sources is not implemented yet; planned.
Can I back up Microsoft 365, Outlook.com or Gmail over IMAP?
Not Microsoft 365 or Outlook.com: Microsoft has switched off IMAP sign-in with a username and password there, so such a connection cannot sign in in any login mode, and Restow says so when you enter a Microsoft IMAP host. Back up Microsoft 365 mailboxes with a Microsoft 365 connection instead. For Gmail and Google Workspace, Restow signs in with a password that Google accepts for IMAP; whether that needs an app password depends on Google's rules for the account, which Restow cannot see, and IMAP must be allowed for it.
Does it back up calendars and contacts?
No. IMAP carries mail only, no calendar and no contacts.
Can I back up an IMAP server inside my own network?
Only by a decision of the operator. Restow connects from its own server, and a tenant administrator may enter only public servers: loopback, private networks and local names are refused. An internal server is allowed for the whole installation by an installation setting, or for one source by a provider administrator who approves its host.
How is mail restored to an IMAP account?
By IMAP append into a target folder, with the original date and flags; the folder is created if it is missing. With "Keep both" (the default) everything goes into a new, clearly named folder and nothing existing is touched; with "Skip existing" mail that is already there, found by its Message-ID, is left alone and only missing mail is restored. No mode overwrites, replaces, deletes or moves anything in the target account. You can also download mail as .eml files in a ZIP.
What if my hoster gives every mailbox its own password?
Use the mode "One password per mailbox". You add the mailboxes by hand or by CSV import (columns login, name and email, plus an optional password), and you set and test the password of each mailbox in the Directory tab. A mailbox without a working password is shown as "Not protected" and is not backed up until one is set.
Can Restow also archive IMAP mail?
Yes, since 0.4.4, in Business and Service Provider: a mail job can keep an IMAP account in sync for the archive (with IMAP IDLE where the server offers it) and take copies that the mail provider forwards. IMAP archiving is near-time and not complete; a forwarded copy is captured at transport. Backup without these editions works as described above.
Is IMAP backup in the Community edition?
Yes. It is part of the Community core and therefore in every edition, since 0.1.0, and the Community edition has no mailbox limit. Restow is a beta: run it beside your existing backup until you have restored from it yourself.
Documentation
The documentation has the details: connecting sources, IMAP (the three sign-in modes, archiving, forwarded copies), first steps (connecting IMAP step by step) and backup and restore.
Microsoft 365 and IMAP backup, the overview →