@gent
Get it on PyPIPyPI
Docs

Gmail sign-in

The runner reads your Sent folder over IMAP and replies over SMTP. It signs in with an app password or your own OAuth client.

Turn on IMAP

In Gmail, open Settings, then Forwarding and POP/IMAP, and enable IMAP.

Option 1: an app password

An app password is the simpler option. Google requires 2-Step Verification for it. Follow Google's app password steps.

Keep the password in your keychain or password manager. Point password_command in ~/.config/agent-mailbox/config.json at the command that prints it. On macOS, after you store it in a Keychain item named atgent:

"password_command": ["security", "find-generic-password", "-s", "atgent", "-w"]

You can set AGENT_MAILBOX_PASSWORD in your shell instead. The login service does not inherit your shell, so use password_command with automatic startup. Never put the password itself in the config or in command arguments.

Check

Managed accounts often block app passwords.

Some Google Workspace accounts and security settings do not offer app passwords. Use your own OAuth client below. OAuth can still need administrator consent.

Option 2: your own OAuth client

@gent does not include an OAuth client. You create your own client in your own Google Cloud project.

  1. Consent screen

    Configure the OAuth consent screen and audience. For an external app in testing, add your Gmail address as a test user. Sign-ins in testing mode can expire after seven days.

  2. Gmail scope

    Add the scope https://mail.google.com/. IMAP and SMTP need this full mail scope, and Google classifies it as restricted.

  3. Desktop client

    Create an OAuth client of type Desktop app and add its client ID to your config.

    "oauth": {"client_id": "YOUR_DESKTOP_CLIENT_ID.apps.googleusercontent.com"}

    If the token exchange needs the client secret, set oauth.client_secret_command to a command that reads it from your keychain.

  4. Sign in

    Open the printed Google URL and pick the configured account. The CLI waits five minutes for the callback on 127.0.0.1.

    atgent oauth-login
    atgent doctor

The refresh token is stored in the macOS Keychain under agent-mailbox.gmail or in Linux secret-tool. Without a supported keychain, the runner warns and writes a file readable only by you. When oauth is set, it takes priority over the password. Remove the section to go back to the app password.

OAuth has automated test coverage. It has not been verified with a live Google client.

Checked against @gent 0.4.4, the current release on PyPI.