Connect Lumail to Codex and it can read your subscribers, campaigns, workflows and analytics, and draft new ones from the session where you write code. Authentication is a browser sign-in: `config.toml` holds a URL and nothing else.

## Setup: send this to your agent

Paste this into Codex and it does the whole setup for you — configuration, browser login, verification.

<AgentPrompt
  label="Prompt"
  prompt="Read lumail.io/codex/install and set up the Lumail connection for me."
/>

Your agent fetches the machine-readable guide at [lumail.io/codex/install](https://lumail.io/codex/install), writes the config block, and tells you when to approve the browser prompt.

> **Administrator access required:** you must be an owner or admin of the organization you connect. Losing that role blocks the connection immediately.

## Setup: by hand

Add this to `~/.codex/config.toml`:

```toml
[mcp_servers.lumail]
url = "https://lumail.io/mcp"
oauth_resource = "https://lumail.io/mcp"
```

Then sign in:

```bash
codex mcp login lumail
```

A Lumail tab opens in your browser. Sign in, pick the organization the agent may reach, and approve the scopes. Verify with:

```bash
codex mcp list
```

`lumail` should appear at `https://lumail.io/mcp`, connected. Inside the Codex TUI, `/mcp` shows the same. Start a new session before your first Lumail prompt so the tool list is picked up.

> **Migrating from an API token?** Delete the `bearer_token_env_var` line from your `[mcp_servers.lumail]` block. A stale bearer token shadows the OAuth credential and keeps you on the old endpoint.

If your Codex build supports plugin marketplaces, you can install the packaged plugin instead and skip straight to the login:

```bash
codex plugin marketplace add https://github.com/Melvynx/lumail-skills.git
codex plugin install lumail
```

## Why there is no token

`https://lumail.io/mcp` is an OAuth 2.1 protected resource with dynamic client registration. Codex registers itself, runs PKCE, and stores the access token in its own credential store — so committing your dotfiles leaks nothing.

Access tokens carry the selected organization as a signed claim, so a session can never reach another organization in your account. Revoke from the connected-apps list in Lumail settings and access stops on the next request.

## What the connection can do

| Scope          | Access                                                                                                                                     |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `lumail.read`  | Subscribers, tags, custom fields, campaigns and their analytics, send progress, workflows, org stats, senders, snippets, writing style     |
| `lumail.write` | Add subscribers, apply and remove tags in bulk, create and edit campaign drafts, duplicate campaigns, create and configure workflow drafts, enroll subscribers in a workflow |

Example prompts:

<AgentPrompt
  label="Try it"
  prompt={[
    "How did last week's newsletter perform compared to the one before?",
    "Add every trial signup from this CSV and tag them trial-2026.",
    "Draft a re-engagement campaign for subscribers who have not opened in 60 days.",
    "Create a workflow that welcomes new subscribers over five days.",
  ]}
/>

### Not available over OAuth

Sending, scheduling, publishing or activating a workflow, unsubscribing, and every delete are **not registered** on the OAuth endpoint. They are not permission prompts an agent could talk you into — the tools simply do not exist on this connection.

Do that work in the Lumail app, or from your terminal with the CLI, which reaches the full API and signs in with the same browser flow:

```bash
npx lumail auth login
```

## Rate limits

| Plan     | Requests/min |
| -------- | ------------ |
| Free     | 100          |
| Premium  | 700          |
| Business | 2,000        |

Limits are counted per organization.

## Troubleshooting

**OAuth settings are not discovered:** the server URL must be exactly `https://lumail.io/mcp`, without `/api` or `/sse`.

**Tools are missing:** start a new Codex session. The tool list is read at session start.

**"Needs authentication":** re-run `codex mcp login lumail`, and check that no `bearer_token_env_var` line remains in the block.

**No organization is available:** ask an owner to promote your membership to owner or admin.

## Removal

Delete the `[mcp_servers.lumail]` block from `~/.codex/config.toml`, or revoke the authorization from Lumail settings — revoking there cuts access immediately without touching local config.

## Related

- [Claude Code plugin](/docs/ai-integration/mcp-claude)
- [ChatGPT plugin](/docs/ai-integration/chatgpt-plugin)
- [Lumail CLI skill](/docs/ai-integration/skills-cli)
- [MCP Server reference](/docs/api-reference/mcp)