Gmvault is a user friendly command-line tool that setup most of the necessary defaults to quickly sync (backup) your gmail account or restore it to a gmail account.
It should be self-explanatory. Use gmvault -h to see the different options and how the tool works.

./gmvault 

gmvault: error: too few arguments

usage: gmvault [-h] [-v] {sync,restore,check,export} ...

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit

subcommands:
  {sync,restore,check,export}
                        valid subcommands.
    sync                synchronize with a given gmail account.
    restore             restore gmvault-db to a given email account.
    check               check and clean the gmvault-db disk database.
    export              Export the gmvault-db database to another format.

Examples:

a) Get help for each of the individual commands

#> gmvault sync -h
#> gmvault restore --help
#> gmvault check -h
#> gmvault export -h


Gmvault is a command-oriented tool and every Gmvault call needs to contain a subcommand (sync, restore and check).
You will first need to setup the credential (token or password) for the different gmail accounts you want to use prior to syncing or restoring them with Gmvault.
This will allow Gmvault to automatically connect to the accounts you want to work with.

Update 12.08.2012: Google has introduced a 2-step authentication scheme recently. If you have enabled this method, you can still use the OAuth token authentication scheme without any problems. The only requirement is to be on a "verified computer" to generate an OAuth token. If you wish to use the password authentication, you will have to generate an applicationi-specific password for Gmvault.

To authenticate yourself and authorize Gmvault accessing your Gmail account, Gmvault allows users to use a Gmail XOAuth token or your Gmail login password.
The XOAuth authentication is the recommended way to access your account. This method is activated by default.
After the first authentication for a given account, the XOAuth token is stored in $HOME/.gmvault or %HOME% (c:\users\MYUSER) and will be used for consequent authentications.
The following example uses an XOAuth token for accessing a gmail account. If the token has not been created for the used Gmail account, Gmvault will automatically try to create one with your help.
Just follow the instructions given by Gmvault.

!$ ./gmvault sync myuser@gmail.com

Use gmvault-db /home/myuser/gmvault-db.
Oauth will be used for authentication.

gmvault will now open a web browser page in order for you to grant gmvault access to your Gmail.
Please make sure you're logged into the correct Gmail account (myuser@gmail.com) before granting access.
Press ENTER to open the browser. Once you've granted access you can switch back to gmvault.

Press ENTER and Gmvault will launch a browser to allow you granting access on the gmail account you want to use.
Be sure to verify that you are logged on the right account.

Grant access to Gmvault.
You should see this once you have granted access to Gmvault.

Once you have granted access to Gmvault, press one more time ENTER to let Gmvault finish its work.

You should now see the web page on your browser now.
If you don't, you can manually open:

https://www.google.com/accounts/OAuthAuthorizeToken?oauth_token=4%abdedsk-leskdkrs-QM4ZnL6tLDy

Once you've granted gmvault access, press the Enter key.

Below is a screenshot of a complete authentication session on Windows.

Grant access to Gmvault.


After that authentication session, Gmvault will automatically use the XOAuth token stored under $HOME/.gmvault or %HOME% (c:\users\MYUSER) for all session with the MYUSER user.
You can renew a saved oauth token with the option --renew-oauth-tok. You will again go through the Gmail OAuth authentication procedure.

Authentication for Google Apps Business and Education Accounts


You need to use the -2 or --2-legged-oauth optional argument to create a Gmail XOAuth token in case you have a Google Apps Business and Education Account. In that case, you will have to enter interactively your domain's OAuth consumer key as well as your consumer secret in order to create the appropriate OAuth token.

ash-3.2$gmvault sync myuser@gmail.com --2-legged-oauth

Use gmvault-db located in /home/myuser/gmvault-db.

Activate Gmvault db cleaning.
Authentication performed with Gmail XOAuth token.

Initiate interactive session to get XOAuth normal or 2-legged token from Gmail.

Enter your domain's OAuth consumer key: xxxxxxxxx
Enter your domain's OAuth consumer secret: xxxxxxxxx
Connect to Gmail server.
43213 emails to be fetched.
Process email num 0 (imap_id:1) from 2005-10.
Process email num 0 (imap_id:2) from 2005-10.
...
      

Gmvault will then automatically connect to your account to sync your emails for example using the created OAuth token. Use the -2-legged-oauth with --renew-passwd in case you need to renew your token.

    
    sync gmail_test@gmail.com -2 --renew-passwd

Use gmvault-db located in /Users/gaubert/gmvault-db.

Activate Gmvault db cleaning.
Authentication performed with Gmail password.

Please enter gmail password for gmail_test@gmail.com and press ENTER:
    

Authentication with gmail password


If you do not want to use the Gmail XOAuth token (not recommended), you can always use Gmvault with your password.
In that case, you will have to interactively enter your password at the beginning of the Gmvault session.

$./gmvault sync myuser@gmail.com -p 

Use gmvault-db /home/myuser/gmvault-db.
Gmail password will be used for authentication.

Please enter gmail password for myuser@gmail.com and press ENTER:
Connect to Gmail server.
53432 emails to be fetched.
Process email num 0 (imap_id:1) from 2005-10.
Process email num 1 (imap_id:2) from 2005-10.
Process email num 2 (imap_id:3) from 2005-10.
Process email num 3 (imap_id:5) from 2005-10.
...

You can also if necessary store your password in $HOME/.gmvault or %HOME% (c:\users\MYUSER) with --store-passwd command.
The password will be encrypted before to be stored. Note that functionnality is provided for flexibility purposes but is not recommended.
Prefer the XOAuth authentication if you need to automate Gmvault synchronisation and restoration operations.

$./gmvault sync myuser@gmail.com -p --store-passwd

Use gmvault-db /home/myuser/gmvault-db.
Gmail password will be used for authentication.

Please enter gmail password for myuser@gmail.com and press ENTER:
Store password for myuser@gmail.com in $HOME/.gmvault.
Connect to Gmail server.
53432 emails to be fetched.
Process email num 0 (imap_id:1) from 2005-10.
Process email num 1 (imap_id:2) from 2005-10.
Process email num 2 (imap_id:3) from 2005-10.
Process email num 3 (imap_id:5) from 2005-10.
...

Finally, it is also possible to renew your stored password with --renew-passwd.

$./gmvault sync myuser@gmail.com -p --renew-passwd

Use gmvault-db /home/myuser/gmvault-db.
Gmail password will be used for authentication.

Please enter gmail password for myuser@gmail.com and press ENTER:
Store password for myuser@gmail.com in $HOME/.gmvault.
Connect to Gmail server.
53432 emails to be fetched.
Process email num 0 (imap_id:1) from 2005-10.
Process email num 1 (imap_id:2) from 2005-10.
Process email num 2 (imap_id:3) from 2005-10.
Process email num 3 (imap_id:5) from 2005-10.
...

The sync command of Gmvault allows users to backup the Gmail account of their choice.

Sync options

Use gmvault sync -h to get explanations regarding all the options. Examples are also provided after the options details.

$./gmvault sync -h

usage: gmvault sync [-h] [-t TYPE] [-d DB_DIR] [-o] [-p] [--renew-oauth-tok]
                    [--renew-passwd] [--store-passwd] [-r REQ] [-g REQ]
                    [--resume] [--emails-only] [--chats-only] [-e] [-c VAL]
                    [-m] [--no-compression] [--server HOSTNAME] [--port PORT]
                    [--debug]
                    email

positional arguments:
  email                 email to sync with.

optional arguments:
  -h, --help            show this help message and exit
  -t TYPE, -type TYPE, --type TYPE
                        type of synchronisation: full|quick|custom. (default:
                        full)
  -d DB_DIR, --db-dir DB_DIR
                        Database root directory. (default: $HOME/gmvault-db)
  -o, --oauth           use oauth for authentication. (default recommended
                        method)
  -p, --passwd          use interactive password authentication. (not
                        recommended)
  --renew-oauth-tok     renew the stored oauth token via an interactive
                        authentication session.
  --renew-passwd        renew the stored password via an interactive
                        authentication session. (not recommended)
  --store-passwd        use interactive password authentication, encrypt and
                        store the password. (not recommended)
  -r REQ, --imap-req REQ
                        Imap request to restrict sync.
  -g REQ, --gmail-req REQ
                        Gmail search request to restrict sync as defined inhtt
                        ps://support.google.com/mail/bin/answer.py?hl=en&answe
                        r=7190
  --resume, --restart   Resume the sync action from the last saved gmail id.
  --emails-only         Only sync emails.
  --chats-only          Only sync chats.
  -e, --encrypt         encrypt stored email messages in the database.
  -c VAL, --check-db VAL
                        Enable/disable the removal from the gmvault db of the
                        emails that have been deleted from the given gmail
                        account. VAL = yes or no.
  -m, --multiple-db-owner
                        Allow the email database to be synchronized with
                        emails from multiple accounts.
  --no-compression      disable email storage compression (gzip).
  --server HOSTNAME     Gmail imap server hostname. (default: imap.gmail.com)
  --port PORT           Gmail imap server port. (default: 993)
  --debug               Activate debugging info

Different phases of a backup operation

A backup operation is organised in 4 phases:

./gmvault sync foo.bar@gmail.com 

Use gmvault-db located in /home/gmv/gmvault-db.

Activate Gmvault db cleaning.
Authentication performed with Gmail XOAuth token.

Get XOAuth credential from /home/gmv/.gmvault/foo.bar@gmail.com.oauth.

Successfully read oauth credentials.

Connect to Gmail server.

Start emails synchronization.

16 emails to be fetched.
Process email num 0 (imap_id:157650) from 2012-07.
Process email num 1 (imap_id:157660) from 2012-07.
Process email num 2 (imap_id:157676) from 2012-07.
Process email num 3 (imap_id:157679) from 2012-07.
Process email num 4 (imap_id:157689) from 2012-07.
Process email num 5 (imap_id:157697) from 2012-07.
Process email num 6 (imap_id:157698) from 2012-07.
Process email num 7 (imap_id:157722) from 2012-08.
Process email num 8 (imap_id:157723) from 2012-08.
Process email num 9 (imap_id:157724) from 2012-08.
Process email num 10 (imap_id:157727) from 2012-08.
Process email num 11 (imap_id:157733) from 2012-08.
Process email num 12 (imap_id:157736) from 2012-08.
Process email num 13 (imap_id:157738) from 2012-08.
Process email num 14 (imap_id:157740) from 2012-08.
Process email num 15 (imap_id:157741) from 2012-08.
Start chats synchronization.

1 chat messages to be fetched.
Process chat num 0 (imap_id:979) into chats/subchats-1.
Look for emails/chats that are in the Gmvault db but not in Gmail servers anymore.

Read all gmail ids from the Gmvault db. It might take a bit of time ...

Found 38966 email(s) in the Gmvault db.

Call Gmail to check the stored emails against the Gmail emails ids and see which ones have been deleted.

Might take few minutes ...

Will delete 1 email(s) from gmvault db.

gm_id 1409038480496800247 not in the Gmail server. Delete it.

Call Gmail to check the stored chats against the Gmail chats ids and see which ones have been deleted.

Might take few minutes ...

Will delete 0 chat(s) from gmvault db.

Deletion checkup done in 21s.
Synchronisation operation performed in 27s.

All the different phases apart the initialization phase can be deactivated with some options.

Standard syncing

gmvault sync myuser@gmail.com will backup the entire content of your gmail account from the oldest to newest email and the same for your chats.
All the emails and chats will be checked but only the new or modified emails/chats will be updated.
You will also notice that Gmvault tries to estimate how long it will take to backup your entire gmail account every 50 emails.
$./gmvault sync foo.bar@gmail.com 
...

Successfully read oauth credentials.

Connect to Gmail server.

Start emails synchronization.

35965 emails to be fetched.
Process email num 0 (imap_id:1) from 2004-10.
Process email num 1 (imap_id:2) from 2004-10.
...
Process email num 49 (imap_id:56) from 2004-10.

== Processed 50 emails in 6s. 35915 left to be stored (time estimate 1h 11m 50s).==

Process email num 50 (imap_id:58) from 2004-10.
Process email num 51 (imap_id:59) from 2004-10.
...

The Gmvault-db

Gmvault lists all the emails that are backed up on disk.
Your emails are stored in an email database created by default in $HOME/.gmvault-db. The Gmvault-db email database is "simply put", a set of directories containing all emails in EML format (which is text). To have your Gmvault-db in another location, use the option -d or --db-dir.
By default, emails are compressed (use --no-compression to save them in clear). You can also encrypt your emails using the option (-e, --encrypt).

Gmvault-db bonding with Gmail accounts

When you create a Gmvault-db, it is automatically bonded to the email account you would like to backup.
If you try to backup a Gmail account with an email database bonded with another email, Gmvault exits in error.
$./gmvault sync foo.bar@gmail.com

Use gmvault-db located in /Users/myuser/gmvault-db.

Activate Gmvault db cleaning.
Authentication performed with Gmail XOAuth token.

Get XOAuth credential from /Users/myuser/.gmvault/foo.bar@gmail.com.oauth.

Successfully read oauth credentials.

Connect to Gmail server.

Error: The email database /Users/myuser/gmvault-db is already associated with one or many logins: myuser@gmail.com. Use option (-m, --multiple-db-owner) if you want to link it with foo.bar@gmail.com.

=== Exception traceback ===
Traceback (most recent call last):
  File "gmv/gmv_cmd.pyc", line 635, in run
  File "gmv/gmv_cmd.pyc", line 566, in _sync
  File "gmv/gmvault.pyc", line 1126, in sync
  File "gmv/gmvault.pyc", line 790, in _check_email_db_ownership
Exception: The email database /Users/myuser/gmvault-db is already associated with one or many logins: myuser@gmail.com. Use option (-m, --multiple-db-owner) if you want to link it with foo.bar@gmail.com.

=== End of Exception traceback ===

Bonding a Gmvault-db with multiple accounts

If you wish to backup multiple Gmail accounts in one email database, you can use the -m or --multiple-db-owner to force it. Note that in that case, Gmvault will stop deleting emails that have been deleted from the Gmail server.

Gmvault-db Cleaning phase

By default Gmvault will try to delete from the Gmvault-db, all the emails and chats that have been deleted from your Gmail Inbox. It is also possible to disable the Gmvault-db cleaning phase in order to speed-up the syncing operation for example when your quicking syncing your mailbox with Gmvault.

$./gmvault sync foo.bar@gmail.com

Use gmvault-db located in /Users/myuser/gmvault-db.

Activate Gmvault db cleaning.
Authentication performed with Gmail XOAuth token.

Get XOAuth credential from /Users/myuser/.gmvault/foo.bar@gmail.com.oauth.

Successfully read oauth credentials.

Connect to Gmail server.

Quikc sync mode. Check for new emails since 03-Aug-2012.
Start emails synchronization.

118 emails to be fetched.
Process email num 0 (imap_id:157864) from 2012-08.
Process email num 1 (imap_id:157866) from 2012-08.
Process email num 2 (imap_id:157869) from 2012-08.
...
2 chat messages to be fetched.
Process chat num 0 (imap_id:980) into chats/subchats-1.
Process chat num 1 (imap_id:981) into chats/subchats-1.
Look for emails/chats that are in the Gmvault db but not in Gmail servers anymore.

Read all gmail ids from the Gmvault db. It might take a bit of time ...

Found 10778 email(s) in the Gmvault db.

Call Gmail to check the stored emails against the Gmail emails ids and see which ones have been deleted.

Might take few minutes ...

Will delete 0 email(s) from gmvault db.

Call Gmail to check the stored chats against the Gmail chats ids and see which ones have been deleted.

Might take few minutes ...

Will delete 0 chat(s) from gmvault db.

Deletion checkup done in 31s.
Synchronisation operation performed in 1m 42s.

Three synchronisation modes

Gmvault provides 3 modes of synchronisations with -t, -type, --type full, quick or custom. The full synchronisation scans your complete email/chat box and store locally emails/chats on disk if they do not exist already. Gmvault uses the full synchronisation type by default.

Quick sync mode

The quick type is used to daily backup your email account automatically (with a cron job for example) and it updates the local email repository with the latest additions.
The quick synchronisation goes up to 7 days backward in time and update your local email repository to reflect the addition and deletion of emails/chats as well as their labels and flags modifications.
You can increase or reduce the number of days to check by changing the value of the property quick_days in the configuration file $HOME/.gmvault/gmvault_defaults.conf (%HOME%/.gmvault/gmvault_defaults.conf for windows). This could allow having a faster syncing phase of example.
See below a quick sync.
$>./gmvault sync foo.bar@gmail.com -t quick
...
Successfully read oauth credentials.

Connect to Gmail server.

Quick sync mode. Check for new emails since 22-Jul-2012.
Start emails synchronization.

137 emails to be fetched.
Process email num 0 (imap_id:156993) from 2012-07.
Process email num 1 (imap_id:156994) from 2012-07.
Process email num 2 (imap_id:157000) from 2012-07.
Process email num 9 (imap_id:157048) from 2012-07.
....
Start chats synchronization.

1 chat messages to be fetched.
Process chat num 1 (imap_id:979) into chats/subchats-1.
Look for emails/chats that are in the Gmvault db but not in Gmail servers anymore.

Read all gmail ids from the Gmvault db. It might take a bit of time ...

Found 38966 email(s) in the Gmvault db.

Call Gmail to check the stored emails against the Gmail emails ids and see which ones have been deleted.
...
Will delete 0 chat(s) from gmvault db.

Deletion checkup done in 21s.
Synchronisation operation performed in 42s.

Custom sync mode

The final type of synchronisation is the custom synchronisation which allows to provide a custom imap or gmail request to only backup a subset of your chats/emails. Gmvault support the IMAP requesting language (see rfc3501) or the dedicated Gmail requesting used to perform search requests (for more info see gmail imap extension).
$> gmvault sync --type custom --imap-req 'Since 1-Nov-2011 Before 10-Nov-2011' 'foo.bar@gmail.com' -c no

Use gmvault-db located in /home/gmv/gmvault-db.

Disable deletion of emails that are in Gmvault db and not anymore in Gmail.
Authentication performed with Gmail XOAuth token.

Get XOAuth credential from /home/gmv/.gmvault/foo.bar@gmail.com.oauth.

Successfully read oauth credentials.

Connect to Gmail server.

Perform custom synchronisation with imap request: Since 1-Nov-2011 Before 10-Nov-2011.

Start emails synchronization.

5 emails to be fetched.
Process email num 0 (imap_id:136823) from 2011-11.
Process email num 1 (imap_id:136913) from 2011-11.
Process email num 2 (imap_id:137006) from 2011-11.
Process email num 3 (imap_id:137059) from 2011-11.
Process email num 4 (imap_id:137092) from 2011-11.
Start chats synchronization.

2 chat messages to be fetched.
Process chat num 0 (imap_id:881) into chats/subchats-1.
Process chat num 1 (imap_id:882) into chats/subchats-1.
Synchronisation operation performed in 4s.


================================================================
Number of reconnections: 0.
Number of emails quarantined: 0.
Number of emails that could not be fetched: 0.
Number of emails that were returned empty by gmail: 0
================================================================

$> gmvault sync --type custom --gmail-req 'in:work from:foo.bar@mycompany.com' 'foo.bar@gmail.com' -c no

Use gmvault-db located in /home/gmv/gmvault-db.

Disable deletion of emails that are in Gmvault db and not anymore in Gmail.
Authentication performed with Gmail XOAuth token.

Get XOAuth credential from /home/gmv/.gmvault/foo.bar@gmail.com.oauth.

Successfully read oauth credentials.

Connect to Gmail server.

Perform custom synchronisation with gmail request: in:work from:foo.bar@mycompany.com.

Start emails synchronization.

60 emails to be fetched.
Process email num 0 (imap_id:107292) from 2010-06.
Process email num 1 (imap_id:107307) from 2010-06.
Process email num 2 (imap_id:109572) from 2010-07.
Process email num 3 (imap_id:109978) from 2010-07.
...
Process email num 58 (imap_id:156832) from 2012-07.
Process email num 59 (imap_id:158415) from 2012-08.
Start chats synchronization.

0 chat messages to be fetched.
Synchronisation operation performed in 39s.


================================================================
Number of reconnections: 0.
Number of emails quarantined: 0.
Number of emails that could not be fetched: 0.
Number of emails that were returned empty by gmail: 0
================================================================

Encrypt your emails

Emails can be encrypted with the option -e --encrypt. With that option, the Blowfish encryption is used to crypt your emails and chats and the first time you activate it, a secret key is randomly generated and stored in $HOME/.gmvault/token.sec.
Keep great care of the secret key as if you loose or delete it your stored emails won't be readable anymore !!!

$>./gmvault sync foo.bar@gmail.com --encrypt

Use gmvault-db located in /home/gmv/gmvault-db.

Activate Gmvault db cleaning.
Authentication performed with Gmail XOAuth token.

Get XOAuth credential from /home/gmv/.gmvault/foo.bar@gmail.com.oauth.

Successfully read oauth credentials.

Connect to Gmail server.

Encryption activated. All emails will be encrypted before to be stored.
Please take care of the encryption key stored in (/home/gmv/gmvault-db/.info/.storage_key.sec) or all your stored emails will become unreadable.
Start emails synchronization.

39061 emails to be fetched.
Process email num 0 (imap_id:1) from 2004-10.
Process email num 1 (imap_id:2) from 2004-10.
Process email num 2 (imap_id:3) from 2004-10.
Process email num 3 (imap_id:5) from 2004-10.
Process email num 4 (imap_id:6) from 2004-10.
Process email num 5 (imap_id:7) from 2004-10.
...

Resuming your backup operation

If the backup operation had to be stopped or was stopped, it is possible to resume it with the --resume --restart option. Gmvault will resume the sync operation close to the last email it was saving. This option is very convenient because it is not uncommon in a full sync to have Gmail closing the connection.

$>./gmvault sync foo.bar@gmail.com --resume

Use gmvault-db located in /home/gmv/gmvault-db.

Activate Gmvault db cleaning.
Authentication performed with Gmail XOAuth token.

Get XOAuth credential from /home/gmv/.gmvault/foo.bar@gmail.com.oauth.

Successfully read oauth credentials.

Connect to Gmail server.

Start emails synchronization.

Restart mode activated for emails. Need to find information in Gmail, be patient ...
Restart from gmail id 1150277043649143517 (imap id 24).
39042 emails to be fetched.
Process email num 0 (imap_id:24) from 2007-05.
Process email num 1 (imap_id:25) from 2007-05.
....

Syncing separately your emails or chats

The options --emails-only and --chats-only can be used to sync separately your emails or your chats. It can also be used to avoid synchronizing your emails when you just want to get your chats for example.

$>./gmvault sync foo.bar@gmail.com --chats-only 

Use gmvault-db located in /home/gmv/gmvault-db.

Activate Gmvault db cleaning.
Authentication performed with Gmail XOAuth token.

Get XOAuth credential from /home/gmv/.gmvault/foo.bar@gmail.com.oauth.

Successfully read oauth credentials.

Connect to Gmail server.

Skip emails synchronization.

Start chats synchronization.

160 chat messages to be fetched.
Process chat num 0 (imap_id:52) into chats/subchats-1.
Process chat num 1 (imap_id:78) into chats/subchats-1.
Process chat num 2 (imap_id:79) into chats/subchats-1.
Process chat num 6 (imap_id:237) into chats/subchats-1.
...
Process chat num 158 (imap_id:975) into chats/subchats-1.
Process chat num 159 (imap_id:979) into chats/subchats-1.
Look for emails/chats that are in the Gmvault db but not in Gmail servers anymore.

Read all gmail ids from the Gmvault db. It might take a bit of time ...

Found 10661 email(s) in the Gmvault db.

Call Gmail to check the stored emails against the Gmail emails ids and see which ones have been deleted.

Might take few minutes ...

Will delete 0 email(s) from gmvault db.

Call Gmail to check the stored chats against the Gmail chats ids and see which ones have been deleted.

Might take few minutes ...

Will delete 0 chat(s) from gmvault db.


Deletion checkup done in 7s.
Synchronisation operation performed in 1m 7s.

...

You can use the restore command to recreate your gmail account in case of problems. Like the sync command the restore command provides 2 types of restore with -t, --type full or quick. The full restore will try to restore completly the local email repository into the given email account while the quick restore will only restore the last 2 months of emails. Restore only upload new emails onto your given gmail account and also update the associated information such as labels but never delete an email from inbox.

Complete Restore
$> ./gmvault restore -d ~/gmvault-db anewfoo.bar@gmail.com

Use gmvault-db located in /home/gmv/gmvault-db.

Authentication performed with Gmail XOAuth token.

Get XOAuth credential from /home/gmv/.gmvault/anewfoo.bar@gmail.com.oauth.

Successfully read oauth credentials.

Connect to Gmail server.

Start emails restoration.

Restore emails in gmail account anewfoo.bar@gmail.com. 
Read email info from /home/gmv/gmvault-db gmvault-db.
Total number of elements to restore 10661.
Got all emails id left to restore. Still 10661 emails to do.

Restore email with id 1150164015313936029.
Restore email with id 1150164486926497027.
Restore email with id 1150164511015697866.
...
Quick restore

A Quick restore will restore only the last month of your emails to make regular incremental updates of your gmail mirror account.

$> ./gmvault restore --type quick -d ~/gmvault-db anewfoo.bar@gmail.com

Use gmvault-db located in /home/gmv/gmvault-db.

Authentication performed with Gmail XOAuth token.

Get XOAuth credential from /home/gmv/.gmvault/anewfoo.bar@gmail.com.oauth.

Successfully read oauth credentials.

Connect to Gmail server.

Start emails restoration.

Quick mode activated. Will only restore all emails since 2012-07.

Restore emails in gmail account gsync.mtester@gmail.com.
Read email info from /home/gmv/gmvault-db gmvault-db.
Total number of elements to restore 220.
Got all emails id left to restore. Still 220 emails to do.

Restore email with id 1150187895023141719.
Restore email with id 1150203908444884403.
...

Note that if you have ten thousands of emails, the restore operation can take more than a day even with a good Internet connection !!! In general on standard internet connections, the upload way is a tenth of the download one and Google also tend to throttle the connection in that way. It is also possible to have the Gmail Server closing and ending the connection after multiple hours. In that case, you can use the --resume to restart the restore operations close to where it failed (up to 10 emails before the failure).

$>./gmvault restore mynewfoo.bar@gmail.com --resume

Use gmvault-db located in /home/gmv/gmvault-db.

Authentication performed with Gmail XOAuth token.

Get XOAuth credential from /home/gmv/.gmvault/anewfoo.bar@gmail.com.oauth.

Successfully read oauth credentials.

Connect to Gmail server.

Start emails restoration.

Restore emails in gmail account gsync.mtester@gmail.com.
Read email info from /home/gmv/gmvault-db gmvault-db.
Total number of elements to restore 10660.
Restart from gmail id 1150187728613013818.
Got all emails id left to restore. Still 10650 emails to do.

Restore email with id 1150187895023141719.
Restore email with id 1150203908444884403.
...

Encrypted emails will be automatically deciphered by Gmvault if it can access the secret key used to encode them.
If it also possible to apply a given label to the current update you are performing:

$>./gmvault restore --label "20120422-gmvault-restore" -d ~/gmvault-db anewfoo.bar@gmail.com
This will apply "20120422-gmvault-restore" to all restored emails.


Gmvault allows you to export your gmvault-db or part of it as a standard mailbox format such as maildir or mbox. Exporting your saved gmvault-db into one fo this format allows your to easily import your emails into a non-Gmail onlline mailbox (yahoo, outlook, ...) or to simply visualise them with your favorite email client such as Dovecot, Thunderbird.

Export Options

Use gmvault export -h to get explanations regarding all the options. Examples are also provided after the options details.

$>gmvault export -h

usage: gmvault export [-h] [-d DB_DIR] [-t TYPE] [-l LABEL] [--debug]
                      output_dir

positional arguments:
  output_dir            destination directory to export to.

optional arguments:
  -h, --help            show this help message and exit
  -d DB_DIR, --db-dir DB_DIR
                        Database root directory. (default: $HOME/gmvault-db)
  -t TYPE, -type TYPE, --type TYPE
                        type of export: offlineimap, dovecot, maildir, mbox.
                        (default: mbox)
  -l LABEL, --label LABEL
                        specify a label to export
  --debug, -debug       Activate debugging info

Warning: Experimental Functionality requiring more testing.

Examples:

a) Export default gmvault-db ($HOME/gmvault-db or %HOME$/gmvault-db) as a maildir mailbox.

#> gmvault export ~/my-mailbox-dir

b) Export a gmvault-db as a mbox mailbox (compliant with Thunderbird).

#> gmvault export -d /tmp/gmvault-db /tmp/a-mbox-dir

c) Export only a limited set of labels from the default gmvault-db as a mbox mailbox (compliant with Thunderbird).

#> gmvault export -l "label1" -l "TopLabel/LabelLev1" /tmp/a-mbox-dir

d) Use one of the export type dedicated to a specific tool (dovecot or offlineIMAP)

#> gmvault export -t dovecot /tmp/a-dovecot-dir

Create a Default mbox Export

By default the export function will create a mbox mailbox storage which is compliant with Thunderbird.

$>gmvault export /tmp/my-mbox-export -d /home/myuser/gmvault-db/

Export gmvault-db as mbox mailbox.
Start emails export for default labels.
== Processed 200 emails in 3s, 11746 left (time estimate 2m 56s). ==

== Processed 400 emails in 9s, 11546 left (time estimate 4m 20s). ==

== Processed 600 emails in 17s, 11346 left (time estimate 5m 21s). ==

....

== Processed 11200 emails in 4m 23s, 146 left (time estimate 24s). ==

== Processed 11346 emails in 4m 47s, 0 left (time estimate 0s). ==

Export complete in 4m48s.
Start chats export for default labels.
Export complete in less than a second.
$>

Change the format of exported mailbox

Using the option -t, --type, different formats for the exported mailbox can be chosen. The gmvault-db mailbox can be exported as maildir, mbox in their standard form or as dedicated variant of these formats that can be used with dovecot or offlineimap.

$>gmvault export /tmp/my-mbox-export -d /home/myuser/gmvault-db/ -t offlineimap

Export gmvault-db as offlineimap mailbox.
Start emails export for default labels.
== Processed 200 emails in 3s, 11746 left (time estimate 2m 56s). ==

== Processed 400 emails in 9s, 11546 left (time estimate 4m 20s). ==

== Processed 600 emails in 17s, 11346 left (time estimate 5m 21s). ==

....

== Processed 11200 emails in 4m 23s, 146 left (time estimate 24s). ==

== Processed 11346 emails in 4m 47s, 0 left (time estimate 0s). ==

Export completed in 4m48s.
Start chats export for default labels.
Export completed in less than a second.
$>

Export specific labels

Using the option -l, --label, it is possible to only export specific labels. If you wish to export nested label such as "lev1/lev2" use that syntax. Repeat the option -l to export more than one label.

$>gmvault export /tmp/my-mbox-export -d /home/myuser/gmvault-db/ -l "lev1/lev2" -l "work

Export gmvault-db as mbox mailbox.
Start emails export for labels lev1/lev2; work.
== Processed 200 emails in 3s, 11746 left (time estimate 2m 56s). ==

== Processed 400 emails in 9s, 11546 left (time estimate 4m 20s). ==

== Processed 600 emails in 17s, 11346 left (time estimate 5m 21s). ==

....

== Processed 11200 emails in 4m 23s, 146 left (time estimate 24s). ==

== Processed 11346 emails in 4m 47s, 0 left (time estimate 0s). ==

Export completed in 4m48s.
Start chats export for labels lev1/lev2; work.
Export completed in less than a second.
$>