New: campaigns, automations and product emails in the same account. Meet Postal
Sign in Create account
Command lineCompatible per the specificationChecked on 10/28/2026

Connect Codex to Postal

Set up Postal in Codex (CLI, IDE extension and app) with a few lines in config.toml.

See how to connect
How you sign in
Account or key
Transport
HTTP
Recommended access
Read and send
1

Before you start

Check these points before opening the Codex setup. They prevent most connection failures.

  • A team with the "MCP server" plan feature (mcp_access); without it the server responds 403 plan_limit_reached.
  • To send emails, the team needs at least one verified domain.
  • If you will use an API key: create the key in the dashboard, under API keys. It starts with ps_; a send-only key is enough if you will only send.
  • Each connection acts on a single team. To use another team, connect again and pick the other one.
  • Connections are listed under Settings › AI connections in the dashboard, where they can be revoked at any time.

What Codex requires

Codex with support for Streamable HTTP and OAuth MCP servers (the documentation does not state a minimum version or plan). Default timeouts: 10 s to start and 60 s per tool call (tool_timeout_sec). The ChatGPT web app does not read config.toml: use the ChatGPT connector there.

2

Connect

Follow the steps in order. The server address is always https://api.postal.so/mcp. Recommended path: sign in with your account (OAuth). The API key is the alternative.

  1. 1

    Edit ~/.codex/config.toml (or .codex/config.toml in a trusted project) and add the block below.

  2. 2

    Run: codex mcp login postal. Codex opens the browser for the Postal login (choose the team and click Allow).

  3. 3

    Check with: codex mcp list. The CLI, the IDE extension and the app use the same configuration.

  4. 4

    For an API key, use the second block and export POSTAL_API_KEY in the environment.

  5. 5

    To request fewer scopes, add scopes = ["mcp:read", "mcp:send"] to the server block.

OAuth (recommended)

~/.codex/config.toml
[mcp_servers.postal]
url = "https://api.postal.so/mcp"

API key

~/.codex/config.toml
[mcp_servers.postal]
url = "https://api.postal.so/mcp"
bearer_token_env_var = "POSTAL_API_KEY"

Login

Terminal
codex mcp login postal
3

Access the tool needs

Postal splits access into three levels, explained in the scopes table. For Codex:

Required
Read your datamcp:read

View emails, domains, contacts, segments, topics, templates, broadcasts, automations, forms, inbox conversations, metrics and usage.

Recommended
Send emails and eventsmcp:send

Send and schedule emails from verified domains and record events for automations.

Only if you want
Manage everythingmcp:full

Everything above, plus creating, changing and deleting contacts and templates, creating and sending broadcasts (send_broadcast requires confirm: true), canceling scheduled emails and working in inboxes (organize, reply, create drafts).

Without the scopes key, Codex uses the scopes the server announces (all three). For development use, mcp:read + mcp:send cover looking up deliveries and sending test emails; mcp:full only for the agent to change templates, contacts and broadcasts.

4

How to confirm it worked

The simplest proof is to ask for something read-only inside Codex itself. The connection also shows up under Settings › AI connections in the Postal dashboard, with the app, the team and the last use.

Illustrative example

List my domains on Postal.
I found 2 domains on the Aurora Cosméticos team: exemplo.com.br (verified) and loja.exemplo.com.br (verifying).

For those who want the technical proof

Terminal: tool list with an API key
npx @modelcontextprotocol/inspector --cli https://api.postal.so/mcp \
  --transport http \
  --header "Authorization: Bearer ps_..." \
  --method tools/list
34Tools expected with a full-access key

The Inspector proves that the Postal server responds. It does not test Codex itself. The full walkthrough is in Validate the connection.

5

If something goes wrong

Go through the list in order. Then read what we know (and what we don't know) about Codex.

Check

  • The address is exactly https://api.postal.so/mcp, with /mcp at the end.
  • The connection type is HTTP (Streamable HTTP). Postal does not offer SSE: if the tool gives you the choice, use HTTP.
  • The team has the "MCP server" feature on its plan. Without it, the server responds 403 plan_limit_reached.
  • To send emails, the team has at least one verified domain.
  • Each connection acts on a single team. To use another one, connect again and pick the other.
  • 429 response (rate_limit_exceeded): the plan's requests-per-second limit was reached. Wait a moment and try again.
  • If the tool complains about the response size, ask for smaller lists (at most 100 items per call; the default is 20).
  • To start over from scratch, revoke the connection under Settings › AI connections and connect again.

What was tested and what was not

Compatible per the specificationChecked on 10/28/2026

We followed the app's specification and documentation, but have not yet tested with the real app. Below is the full note on what was and was not verified.

Test details

Verified by test: Codex's default redirect (http://127.0.0.1:PORTA/callback) is accepted in dynamic registration and in the full flow; the API key as Bearer is the same path verified with the SDK. Codex can also use a Client ID Metadata Document when the server announces it, but we could not find its URL or the content of its document, so that path was not tested; dynamic registration (which Codex uses as a fallback) was. Not tested with the real Codex.

Frequently asked questions

Do I need an API key to connect Codex?

Not required. Codex can sign in with your Postal account (OAuth) or with an API key. Recommended path: sign in with your account (OAuth). The API key is the alternative. The send-only key (sending_access) exposes only send_email and track_event.

Can I limit what Codex does on my account?

Without the scopes key, Codex uses the scopes the server announces (all three). For development use, mcp:read + mcp:send cover looking up deliveries and sending test emails; mcp:full only for the agent to change templates, contacts and broadcasts. You can revoke the connection at any time under Settings › AI connections.

Official Codex documentationPostal MCP serverAuthentication and keysAll tools

Keep going

Other tools

Each tool has its own walkthrough. See also the full list under AI.

GitHub Copilot

Use Postal in GitHub Copilot: in VS Code via OAuth, in the Copilot CLI and in the Copilot cloud agent with an API key.

See how to connect

Gemini

Connect Postal to the Gemini CLI (and to Antigravity, which replaces it for those without a paid plan) to look up and send emails from the terminal.

See how to connect

v0

Connect Postal to v0 so it can look up your domains and templates and send test emails while it generates the app.

See how to connect

Ready to use Postal in Codex?

Create your account and connect. If you need help, talk to us through the contact form.

Create accountSee all tools