# Multi Mailbox Gmail for Codex

An open-source **Codex plugin** for connecting and searching multiple Gmail and Google Workspace accounts by friendly aliases such as `@personal` and `@work`.

It extends Codex with a local MCP server and mailbox-aware instructions, so a request such as `Search @personal and @work for recent invoices` searches both selected accounts and identifies the source mailbox for every result. Mail access is read-only.

## Release status

| Capability | Current status |
| --- | --- |
| Public GitHub repository and Codex installation | Available |
| Codex on Windows | Supported |
| Codex on macOS | Experimental — uses macOS Keychain |
| Codex on Linux | Experimental — requires Secret Service and `secret-tool` |
| Search multiple named Gmail accounts | Available after OAuth setup |
| Bring your own Google Desktop OAuth client | Available |
| One-click `Connect @alias` for non-developers | **Not live yet** — shared public OAuth client and Google verification are pending |

The repository is public, but it is currently a developer preview. Until the shared OAuth client is added, an outside user can install the Codex plugin but must supply their own Google Desktop OAuth credentials before connecting a mailbox.

## Install in Codex

```powershell
npx codex-marketplace add pkforge/multi-mailbox-gmail --plugin
```

Start a new Codex task after installation so the plugin's skill and MCP tools are loaded.

## Connect mailboxes in chat

Once the shared public OAuth client is live, users will start a new Codex task and say:

```text
Connect @personal
Connect @work
```

Each command opens Google's account chooser. Pick the account that should own that alias and approve read-only Gmail access. Repeat for as many accounts as you need.

The planned public build will use one shared Google **Desktop app** identity so end users do not need a Google Cloud account or developer setup. OAuth happens directly between this local plugin and Google: there is no publisher backend, database, analytics, or telemetry. The plugin requests only `https://www.googleapis.com/auth/gmail.readonly`. Refresh tokens are encrypted for the current Windows user with DPAPI; aliases and account email addresses are stored as local metadata under `%LOCALAPPDATA%\MultiMailboxGmail`.

## Current setup: use your own OAuth client

Organizations that prefer their own Google Cloud project can create a Desktop OAuth client, enable the Gmail API, and either pass its downloaded JSON to the CLI or set `MULTI_MAILBOX_GMAIL_OAUTH_CLIENT_FILE`.

```powershell
npm.cmd install
npm.cmd run mailbox -- add personal C:\path\to\oauth-client.json
npm.cmd run mailbox -- add work C:\path\to\oauth-client.json
npm.cmd run mailbox -- list
```

Each `add` command opens Google sign-in. Choose the account that should own that alias.

Remove locally stored credentials with:

```powershell
npm.cmd run mailbox -- remove work
```

This removes the local encrypted token. You can separately revoke the app from the Google Account security page if desired.

## Use in chat

- `Search @personal and @work for invoices from the last 90 days.`
- `Search @finance for unread mail with attachments.`
- `Search all mailboxes for subject:renewal newer_than:1y.`

The plugin returns each message with its source alias, so identical messages remain attributable to the correct mailbox.

## Public release work remaining

Before non-developers can use `Connect @alias` without Google Cloud setup, the project owner must:

1. Finish the Google OAuth consent-screen configuration.
2. Create and publish the installed-app OAuth client identity.
3. Test the end-to-end Codex connection flow with multiple accounts.
4. Submit the restricted Gmail read-only scope for Google's public-app verification.

During review, Google may show an unverified-app warning and enforce its unverified-user cap. The source code and bring-your-own-client path remain usable.

This is an independent community project and is not affiliated with or endorsed by Google or OpenAI.

See [Privacy](./PRIVACY.md), [Security](./SECURITY.md), and the [Google verification package](./docs/verification.md).