Install guide

Connect Mailcheer to Codex

Codex reads MCP servers from its configuration file, or from its command line.

Create an API key
In your Mailcheer workspace: Settings → API → New key. Name it, tick the permissions, save. The key is shown ONCE — copy it immediately. It starts with mch_live_ followed by thirty-two characters.
02
From the command line
Codex reads the key from an environment variable and sends it in the Authorization header itself. Replace YOUR_KEY; add the export line to your shell profile so it survives closing the terminal. The command writes to ~/.codex/config.toml for you.
```
export MAILCHEER_API_KEY="YOUR_KEY"
codex mcp add mailcheer \
  --url https://mailcheer.com/api/mcp \
  --bearer-token-env-var MAILCHEER_API_KEY
```
03
Or manually, in ~/.codex/config.toml
The same thing, written in the configuration file. The environment variable is still required: the key is never written to the file.
```
[mcp_servers.mailcheer]
url = "https://mailcheer.com/api/mcp"
bearer_token_env_var = "MAILCHEER_API_KEY"
```
04
Check that it's connected
Ask for the account status. This is read-only: nothing is modified, nothing is sent. The response names your workspace and lists your verified sending domains — those are the addresses you can send from.
```
In the session: "What Mailcheer workspace do you see, and which sending domains are verified?"
```

Troubleshooting

Every API error carries a readable code. Here are the ones you encounter when connecting.

401 invalid_api_key	The key is incomplete (a newline crept in during copy-paste) or has been replaced. Create a new one.
401 revoked_api_key	The key was cut under Settings → API. Create another one.
403 insufficient_scope	The key does not have the required permission. Permissions are chosen at creation and cannot be changed: create a key with the right scope.
422 unverified_from_domain	The sending address is not on a verified domain in the workspace. The error message lists the ones that are. To add one: Domains → Add a domain, then set the DNS records.
429 rate_limit_exceeded	More than 600 requests per minute for this key. The Retry-After header says how many seconds to wait.