Google OAuth Setup

msgvault requires OAuth credentials to access the Gmail API. This guide walks through the complete setup.

Step 1: Create a Google Cloud Project

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Note your project ID

Step 2: Enable the Gmail API

1. Navigate to APIs & Services > Library
2. Search for “Gmail API”
3. Click Enable

Step 3: Configure OAuth Consent Screen

1. Go to APIs & Services > OAuth consent screen
2. Choose External user type (or Internal for Google Workspace)
3. Fill in required fields:
   • App name: msgvault
   • User support email: your email
   • Developer contact email: your email
4. Click Save and Continue
5. On the Scopes page, click Add or Remove Scopes
6. Add the scope: https://www.googleapis.com/auth/gmail.modify
7. Save and continue through the remaining screens
8. Under Test users, add all Gmail addresses you want to sync

Note

The gmail.modify scope enables deletion features while sync operations remain read-only. When you first run delete-staged, msgvault will prompt you to upgrade to full mail.google.com access for batch deletion.

Step 4: Create OAuth Client Credentials

1. Go to APIs & Services > Credentials
2. Click Create Credentials > OAuth client ID
3. Choose Desktop application as the application type
4. Name it msgvault (or similar)
5. Click Create
6. Download the JSON file
7. Save it as client_secret.json in a secure location

Caution

Never commit client_secret.json to version control.

Desktop Application Only

You must choose Desktop application as the client type. Do not use “TVs and Limited Input devices” as Google’s device code flow does not support Gmail scopes.

Step 5: Configure msgvault

Create config.toml in your msgvault data directory:

• macOS / Linux: ~/.msgvault/config.toml
• Windows: C:\Users\<you>\.msgvault\config.toml

Tip

The .msgvault directory is created automatically the first time you run any msgvault command. If you’re unsure of the exact path, run msgvault add-account you@gmail.com; the error message may show you where to create the config file.

[oauth]
client_secrets = "/path/to/your/client_secret.json"

[sync]
rate_limit_qps = 5

On Windows, use forward slashes or escaped backslashes for the path:

[oauth]
client_secrets = "C:/Users/you/Downloads/client_secret.json"

Step 6: Add Your Account

msgvault add-account you@gmail.com

This opens your browser to Google’s OAuth consent page. Sign in, grant access, and tokens are stored locally in ~/.msgvault/tokens/.

Multiple Accounts

A single client_secret.json works for all your Gmail accounts. You do not need separate OAuth credentials, config entries, or projects per account. Each add-account call creates a separate token file — no config changes required between accounts.

# Same client_secret.json, different accounts
msgvault add-account personal@gmail.com
msgvault add-account work@company.com
msgvault add-account other@gmail.com

# Sync all at once — no config editing needed
msgvault sync

Each account goes through its own browser authorization once. After that, msgvault sync refreshes all tokens automatically.

Tip

Make sure all Gmail addresses you want to sync are listed as Test users in your Google Cloud OAuth consent screen (Step 3 above). This is the most common reason a second account fails to authorize.

Headless Server Setup

When running msgvault on a headless server (SSH, VPS, Docker), there is no browser available for OAuth. Google’s device code flow does not support Gmail scopes, so you must authorize on a machine with a browser and copy the token to your server.

Run --headless to see the setup instructions:

msgvault add-account you@gmail.com --headless

This prints:

=== Headless Server Setup ===

Google's OAuth device flow does not support Gmail scopes, so --headless
cannot directly authorize. Instead, authorize on a machine with a browser
and copy the token to your server.

Step 1: On a machine with a browser, run:

    msgvault add-account you@gmail.com

Step 2: Copy the token file to your headless server:

    ssh user@server 'mkdir -p ~/.msgvault/tokens'
    scp ~/.msgvault/tokens/you@gmail.com.json user@server:~/.msgvault/tokens/

Step 3: On the headless server, register the account:

    msgvault add-account you@gmail.com

The token will be detected and the account registered. No browser needed.

Step-by-Step

1. On your local machine (with a browser), install msgvault and run:

   msgvault add-account you@gmail.com

   Complete the OAuth flow in your browser.

2. Copy the token to your headless server:

   ssh user@server mkdir -p ~/.msgvault/tokens
   scp ~/.msgvault/tokens/you@gmail.com.json user@server:~/.msgvault/tokens/

3. On the headless server, register the account:

   msgvault add-account you@gmail.com

   msgvault detects the existing token and registers the account. Output:

   Account you@gmail.com is ready.
   You can now run: msgvault sync-full you@gmail.com

4. Sync your email:

   msgvault sync-full you@gmail.com

The token file contains OAuth refresh tokens that are automatically renewed. You only need to copy it once unless you revoke access.

Note

Both machines must have the same client_secret.json configured, or use the same OAuth client credentials. The token is tied to the OAuth client that created it.