gmail-archiver

Python versions PyPI - Version GitHub tag (with filter) License GitHub commits since latest release (by SemVer including pre-releases) CodeQL QA Tests Coverage Status Dependabot Documentation Status mypy uv pytest Ruff Downloads Stargazers pre-commit.ci status Prettier Follow @Tatsh Mastodon Follow

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:

0 on success, 1 if an error occurred while processing messages.

Return type:

int

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:
url : str

The token endpoint URL.

client_id : str

The OAuth client identifier.

client_secret : str

The OAuth client secret.

authorization_code : str

The authorisation code from the redirect.

verifier : str

The PKCE code verifier.

redirect_uri : str

The redirect URI used in the authorisation request.

scope : str

The requested OAuth scope.

Returns:

Token response fields from the authorisation server.

Return type:

AuthInfo

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.

Parameters:
url : str

The token endpoint URL.

client_id : str

The OAuth client identifier.

client_secret : str

The OAuth client secret.

refresh_token : str

The refresh token.

Returns:

Token response fields from the authorisation server.

Return type:

AuthInfo

Typing helpers.

gmail_archiver.typing.AuthDataDB

Dictionary of OAuth information for different users.

alias of dict[str, AuthInfo]

class gmail_archiver.typing.AuthInfo

OAuth information.

access_token : str

Access token.

expiration_time : str

Expiration time of the access token.

expires_in : int

Time in seconds until the access token expires.

refresh_token : str

Refresh token.

class gmail_archiver.typing.Config

Configuration for the archiver.

client_id : str

Client ID for OAuth2.

client_secret : str

Client secret for OAuth2.

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, and token_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:
auth_code_callback : Callable[[str], None]

Called with the authorisation code from the query string.

Returns:

The handler class to pass to HTTPServer.

Return type:

type[http.server.BaseHTTPRequestHandler]

gmail_archiver.utils.get_localhost_redirect_uri() → tuple[int, str]

Find an available port and return a localhost URI.

Returns:

The listen port and http://localhost:{port}/ redirect URI.

Return type:

tuple[int, str]

Raises:

TypeError – If the bound socket does not report an integer port.

Indices and tables