{"id":19361591,"url":"https://github.com/mxk/gmdb","last_synced_at":"2025-08-24T21:22:46.316Z","repository":{"id":34956801,"uuid":"39032101","full_name":"mxk/gmdb","owner":"mxk","description":"Gmail Backup Database","archived":false,"fork":false,"pushed_at":"2015-07-13T19:15:03.000Z","size":280,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-06T19:47:33.626Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mxk.png","metadata":{"files":{"readme":"README","changelog":"CHANGES","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-07-13T19:13:43.000Z","updated_at":"2023-02-25T06:58:39.000Z","dependencies_parsed_at":"2022-09-01T23:40:30.590Z","dependency_job_id":null,"html_url":"https://github.com/mxk/gmdb","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxk%2Fgmdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxk%2Fgmdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxk%2Fgmdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxk%2Fgmdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mxk","download_url":"https://codeload.github.com/mxk/gmdb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240476473,"owners_count":19807523,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-10T07:24:01.846Z","updated_at":"2025-02-24T12:25:51.715Z","avatar_url":"https://github.com/mxk.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\r\nGmail Backup Database\r\n\r\nNAME\r\n\tgmdb -- manage local gmail message database\r\n\r\nSYNOPSIS\r\n\tgmdb command [options] ...\r\n\tgmdb command -h\r\n\tgmdb -h\r\n\r\nDESCRIPTION\r\n\tThe gmdb client allows you backup all mail stored in a Gmail or Google Apps\r\n\taccount to the local storage. The backup is performed using IMAP4 protocol,\r\n\twith some Gmail-specific extensions, which preserves the structure (labels)\r\n\tof all messages. The user has the option of selecting which messages are\r\n\tbacked up by constructing a search query using the same syntax as the web\r\n\tinterface search (see 'backup' command help for more information).\r\n\r\n\tBy default, deleted messages are kept in the database for 1 year, but you\r\n\tmay change this setting to any other value, including forever (see 'config'\r\n\tcommand). Messages may be restored either to Gmail servers (to the same or\r\n\tdifferent account) or to any other IMAP4 server. The restoration can be\r\n\tperformed for the entire account or for a limited number of messages (see\r\n\t'restore' command).\r\n\r\n\tThe client relies heavily on the 'X-GM-EXT1' IMAP4 extensions, which are\r\n\tavailable on Gmail IMAP4 servers. As a result, the client is currently not\r\n\table to back up mail from any other IMAP4 server, but this functionality may\r\n\tbe added in a future release. Contacts, calendar entries, and chat logs are\r\n\talso not currently saved.\r\n\r\nCONFIGURATION FILE\r\n\tAn optional configuration file may be used to customize program behavior.\r\n\tThe configuration file is required when authenticating to a Google Apps\r\n\tdomain using OAuth (see next section). The default search path is:\r\n\r\n\t  (All)     ./gmdb.conf\r\n\t  (Windows) %USERPROFILE%\\gmdb.conf\r\n\t  (Unix)    %HOME/.gmdb\r\n\t  (Unix)    PREFIX/etc/gmdb.conf  (where PREFIX is Python's sys.prefix)\r\n\t  (Unix)    /etc/gmdb.conf\r\n\r\n\tThe exact path may also be specified using the --conf (-c) option. The\r\n\tconfiguration file uses standard Python syntax. The default settings are\r\n\tlisted in _gmdb/conf.py. Here is an example configuration:\r\n\r\n\t  ROOT_DIR     = '/backup/gmail'             # Where backups are stored\r\n\t  OAUTH_KEY    = 'example.org'               # Google Apps domain name\r\n\t  OAUTH_SECRET = 'kmEgIBJL8ox3AKtTSL4TYzQU'  # OAuth consumer secret\r\n\r\nAUTHENTICATION\r\n\tIMAP authentication may be performed using either plaintext password or\r\n\t2-legged OAuth mechanisms. The latter is intended for use with Google Apps\r\n\tdomains and provides a way for administrators to back up all domain accounts\r\n\twithout requiring individual user passwords.\r\n\r\n\tThe plaintext password authentication should be used for individual Gmail\r\n\taccounts. Gmail requires SSL when connecting to their servers, so your\r\n\tpassword is encrypted before being sent over the wire. Even so, you should\r\n\tenable \"2-step verification\" for your account and use an application-\r\n\tspecific password to avoid storing the real password in a file on your\r\n\tcomputer. See the following link for more information:\r\n\r\n\t  http://www.google.com/support/accounts/bin/static.py?page=guide.cs\u0026\r\n\t  guide=1056283\r\n\r\n\tThe preferred way to specify a password is through the --passwd-file (-P)\r\n\toption, which will read the password from a file, the standard input, or the\r\n\tcurrent terminal (depending on what is connected to stdin). This is slightly\r\n\tmore secure than specifying the password on the command line with the -p\r\n\toption, which is visible in the process list and is saved to your command\r\n\thistory. You may also opt to enter the password manually for each\r\n\tbackup/restore operation, which is the most secure, but slightly\r\n\tinconvenient method.\r\n\r\nEXIT STATUS\r\n\tThe program exists with a status of 0 on success, 1 on error, and 2 on an\r\n\terror in command line arguments.\r\n\r\nSTANDARDS\r\n\tBelow is a list of informational URLs that are relevant to the client\r\n\timplementation. A more detailed list of IMAP-specific RFCs is at the top of\r\n\t_gmdb\\imaplib2.py.\r\n\r\n\t* http://tools.ietf.org/html/rfc3501 - IMAP VERSION 4rev1\r\n\t* http://tools.ietf.org/html/rfc5849 - The OAuth 1.0 Protocol\r\n\t* http://code.google.com/apis/accounts/docs/OAuth.html - OAuth for Web Apps\r\n\t* http://code.google.com/apis/gmail/oauth/protocol.html - Gmail IMAP OAuth\r\n\t* http://code.google.com/apis/gmail/imap/ - Gmail IMAP Extensions\r\n\r\nBUGS\r\n\tThe 'muted' message status is not backed up. As far as I can tell, there is\r\n\tno way to retrieve it from the server.\r\n\r\n\tThe 'starred' attribute is not converted to 'flagged' when restoring\r\n\tmessages to Microsoft Exchange server.\r\n\r\n\tCreating a label called '\\Important' and adding messages to it (which is\r\n\tnot the same as marking messages 'important'), will cause those messages to\r\n\tbe restored as 'important' rather than be labeled '\\Important' (confused\r\n\tyet?). In other words, Gmail adds a special flag to each message when you\r\n\tmark it as important via the web interface. However, it doesn't prevent you\r\n\tfrom creating a label by the same name as the flag, which happens to be\r\n\t'\\Important'. During a restore operation, the server can't tell whether\r\n\t'\\Important' refers to the flag or a separate label, so it assumes the\r\n\tformer.\r\n\r\n\tRunning the source distribution on Windows requires an updated SQLite DLL\r\n\tin order for the 'index' command to work. The default DLL distributed with\r\n\tPython 3.2 does not have the FTS module compiled in. The solution is to\r\n\tdownload sqlite3.dll from the official SQLite website and replace the DLL\r\n\tstored in your Python32\\DLLs directory.\r\n\r\n\t(Inconvenience) The restore operation is significantly slower than backup.\r\n\tThis due to the design of IMAP4 protocol. During backup, the client can scan\r\n\tthe attributes of 1000 messages (using the default configuration) and\r\n\tdownload all new messages in that range with just two commands. Restore, on\r\n\tthe other hand, requires three command round-trips for each message. A\r\n\tnumber of extensions have been developed to improve message upload\r\n\tperformance (RFC-2088 and RFC-3502), but Gmail servers do not support them.\r\n\r\n\tPressing \u003cCtrl-C\u003e at the 'Password:' prompt does not cause the program to\r\n\texit immediately; you still need to press \u003cEnter\u003e. This a bug in Python 3.2,\r\n\tsee issue #11236.\r\n\r\n\tThe indexing operation may fail to parse some \"unusual\" (read: malformed)\r\n\tmessages. If you encounter \"Failed to parse message\" errors, please send me\r\n\tthe output of the following command (assuming that the message does not\r\n\tcontain any sensitive information):\r\n\r\n\t  $ gmdb view -d \u003cdigest\u003e \u003caccount\u003e\r\n\r\nAUTHOR\r\n\tMaxim Khitrov \u003cmax@mxcrypt.com\u003e\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmxk%2Fgmdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmxk%2Fgmdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmxk%2Fgmdb/lists"}