gmail-archiver¶
Locally archive Gmail emails.
Commands¶
gmail-archiver¶
Archive Gmail emails and move them to the trash.
Usage
gmail-archiver [OPTIONS] EMAIL [OUT_DIR]
Options
- --no-delete¶
Do not move emails to trash.
- -a, --auth-only¶
Only authorise the user.
- -d, --debug¶
Enable debug level logging.
- -D, --days <days>¶
Archive emails older than this many days. Set to 0 to archive everything.
- --debug-imap¶
Enable debug level logging for IMAP.
- -r, --force-refresh¶
Force refresh the token.
Arguments
- EMAIL¶
Required argument
- OUT_DIR¶
Optional argument
Configuration¶
Create a file at ${CONFIG_DIR}/gmail-archiver/config.toml. On Linux this is typically
~/.config/gmail-archiver/config.toml. The application will print the configuration file path on
every run.
The file must contain the following:
[tool.gmail-archiver]
client_id = 'client-id.apps.googleusercontent.com'
client_secret = 'client-secret'
You must set up a project on Google Cloud and it must have the Gmail API enabled.
Then in APIs and services, choose Credentials, + Create credentials and OAuth client ID.
Application type: Web application
Name: any name
Copy and paste the client ID and secret into the above file.
You should protect the above file. Set it to as limited of a permission set as possible. Example:
chmod 0400 ~/.config/gmail-archiver/config.toml.
Why not use Keyring? Keyring is inappropriate for automated scenarios, unless it is purposely made insecure.
Authorisation¶
When run, if anything is invalid about the OAuth data, you will be prompted to create it.
$ gmail-archiver email@gmail.com
Using authorisation database: /home/user/.cache/gmail-archiver/oauth.json
Using authorisation file: /home/user/.config/gmail-archiver/config.toml
https://accounts.google.com/o/oauth2/v2/auth?client_id=....
Visit displayed URL to authorize this application. Waiting...
In your browser, click Continue and then in the browser you will see the text: Authorisation redirect completed. You may close this window. At that point the archiving will begin.
Visit displayed URL to authorize this application. Waiting...
127.0.1.1 - - [17/May/2025 00:50:21] "GET /?code=...&scope=https://mail.google.com/ HTTP/1.1" 200 -
INFO: Logging in.
INFO: Deleting emails: False
INFO: Archiving 200 messages.
Due to the method of authorisation for OAuth, if you need to run this on a server that does not have a fully-featured browser (such as a headless machine), you must run this tool on a machine with one (and the ability to run a localhost server) to get the first access token. Once this is done, transfer configuration and the OAuth authorisation data to the server. From that point, the access token will be refreshed when necessary. You must do this for every email you plan to archive.
The OAuth authorisation file is also printed at startup. Example on Linux:
~/.config/cache/gmail-archiver/oauth.json. It will be stored with mode 0600.
Library¶
gmail-archiver module.
-
async gmail_archiver.archive_emails(imap_conn: aioimaplib.IMAP4_SSL, email: str, access_token: str, out_dir: AsyncPath, days: int =
90, *, debug: bool =False, delete: bool =False) int¶ Download emails and optionally move them to the trash.
- Parameters:¶
- imap_conn : aioimaplib.IMAP4_SSL¶
The authenticated IMAP connection.
- email : str¶
The mailbox account label used in output paths.
- access_token : str¶
The OAuth2 access token for authentication.
- out_dir : AsyncPath¶
The root directory for archived messages.
- days : int¶
Archive messages older than this many days.
- debug : bool¶
When True, enable verbose IMAP protocol logging.
- delete : bool¶
When True, move archived messages to trash.
- Returns:¶
0on success,1if an error occurred while processing messages.- Return type:¶
-
async gmail_archiver.authorize_tokens(url: str, client_id: str, client_secret: str, authorization_code: str, verifier: str, redirect_uri: str, scope: str =
'https://mail.google.com/') AuthInfo¶ Exchange the authorisation code for an access token.
- Parameters:¶
The token endpoint URL.
The OAuth client identifier.
The OAuth client secret.
The authorisation code from the redirect.
The PKCE code verifier.
The redirect URI used in the authorisation request.
The requested OAuth scope.
- Returns:¶
Token response fields from the authorisation server.
- Return type:¶
- async gmail_archiver.refresh_token(url: str, client_id: str, client_secret: str, refresh_token: str) AuthInfo¶
Refresh the access token using the refresh token.
Typing helpers.
- gmail_archiver.typing.AuthDataDB¶
Dictionary of OAuth information for different users.
- class gmail_archiver.typing.AuthInfo¶
OAuth information.
- class gmail_archiver.typing.Config¶
Configuration for the archiver.
Utilities.
- class gmail_archiver.utils.GoogleOAuthClient(client_id: str, client_secret: str)¶
Uses discovery to get the appropriate endpoint URIs.
- authorization_endpoint¶
OAuth authorisation endpoint URL populated by
discover().
- client_id¶
OAuth client identifier.
- client_secret¶
OAuth client secret.
- device_authorization_endpoint¶
Device authorisation endpoint URL populated by
discover().
- async discover() None¶
Fetch OpenID Connect discovery document and populate endpoints.
Queries Google’s well-known OpenID Connect configuration and sets
authorization_endpoint,device_authorization_endpoint, andtoken_endpoint.
- token_endpoint¶
Token endpoint URL populated by
discover().
- gmail_archiver.utils.get_auth_http_handler(auth_code_callback: collections.abc.Callable[[str], None]) type[http.server.BaseHTTPRequestHandler]¶
Build a request handler class for the local authorisation redirect server.
- Parameters:¶
- Returns:¶
The handler class to pass to
HTTPServer.- Return type:¶
- gmail_archiver.utils.get_localhost_redirect_uri() tuple[int, str]¶
Find an available port and return a localhost URI.