imap-backup
Backup GMail (or other IMAP) accounts to disk
GMail
To use imap-backup with GMail, you will need to enable 'App passwords' on your account.
GMail OAuth2
GMail OAuth2 authentication is supported, but as GMail's policy requires users to set up an application specific to their account, the feature is disabled by default.
You will need to set the environment variable IMAP_BACKUP_ENABLE_GMAIL_OAUTH2.
To set it up, follow the HOWTO.
Installation
$ gem install 'imap-backup'
Setup
In order to do backups, you need to add accounts via a menu-driven command line program:
Run:
$ imap-backup setup
Folders
By default, all folders are backed-up. You can override this by choosing specific folders.
Configuration file
setup
creates the file ~/.imap-backup/config.json
E.g.:
{
"accounts": [
{
"username": "[email protected]",
"password": "secret",
"local_path": "/path/to/backup/root",
"folders":
[
{"name": "[Gmail]/All Mail"},
{"name": "my_folder"}
]
}
]
}
It connects to GMail by default, but you can also specify a server:
{
"accounts": [
{
"username": "[email protected]",
"password": "secret",
"server": "my.imap.example.com",
"local_path": "/path/to/backup/root",
"folders":
[
{"name": "[Gmail]/All Mail"},
{"name": "my_folder"}
]
}
]
}
Connection options
You can override the parameters passed to Net::IMAP
with connection_options
.
Specifically, if you are using a self-signed certificate and get SSL errors, e.g.
certificate verify failed
, you can choose to not verify the TLS connection:
{
"accounts": [
{
"username": "[email protected]",
"password": "secret",
"server": "my.imap.example.com",
"local_path": "/path/to/backup/root",
"folders": [
{"name": "[Gmail]/All Mail"},
{"name": "my_folder"}
],
"connection_options": {
"ssl": {"verify_mode": 0},
"port": 993
}
}
]
}
Security
Note that email usernames and passwords are held in plain text in the configuration file.
The directory ~/.imap-backup, the configuration file and all backup directories have their access permissions set to only allow access by your user.
Run Backup
Manually, from the command line:
$ imap-backup
Alternatively, add it to your crontab.
Result
Each folder is saved to an mbox file. Alongside each mbox is a file with extension '.imap', which lists the source IMAP UIDs to allow a full restore.
Troubleshooting
If you have problems:
- ensure that you have the latest release,
- turn on debugging output:
{
"accounts":
[
...
],
"debug": true
}
Restore
All missing messages are pushed to the IMAP server. Existing messages are left unchanged.
This functionality requires that the IMAP server supports the UIDPLUS extension to IMAP4.
Other Usage
List IMAP folders:
$ imap-backup folders
Get statistics of emails to download per folder:
$ imap-backup status
Design Goals
- Secure - use a local file protected by permissions
- Restartable - calculate start point based on already downloaded messages
- Standalone - do not rely on an email client or MTA
Similar Software
Testing
Integration Tests
Integration tests (feature specs) are run against a Docker image (antespi/docker-imap-devel:latest).
In one shell, run the Docker image:
$ docker run \
--env [email protected] \
--env MAIL_PASS=pass \
--env MAILNAME=example.org \
--publish 8993:993 \
antespi/docker-imap-devel:latest
$ rake
To exclude Docker-based tests:
rake no-docker
or
$ rspec --tag ~docker
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Added some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request