Send & Receive Emails with OpenAI Codex

This page gives Codex its own @agentmail.to inbox: one it creates, sends from, and checks for you.

0. Install Codex

This walkthrough uses the Codex CLI. Install it and sign in:

npm install -g @openai/codex
codex login

You also need an AgentMail account for the sign-in in step 2. Create one at the AgentMail Console. The plugin authenticates with OAuth, so you do not need an API key for this walkthrough.

1. Install the AgentMail plugin

Add the AgentMail marketplace, then install the plugin from it:

codex plugin marketplace add agentmail-to/agentmail-plugins
codex plugin add agentmail@agentmail

The plugin bundles the AgentMail skills and the hosted MCP server, so one install adds both. Confirm it with codex plugin list:

PLUGIN               STATUS              VERSION  PATH
agentmail@agentmail  installed, enabled  0.3.0    ~/.codex/.tmp/marketplaces/agentmail

Start a new Codex session after installing.

In the ChatGPT desktop app, install from the Plugins tab instead: search for AgentMail, select the plus button, and start a new chat.

2. Connect to AgentMail

The first time a session uses an AgentMail tool, Codex opens a browser window on the AgentMail sign-in page. Complete the sign-in there and return to the session. You can also sign in ahead of time:

codex mcp login agentmail

Check the connection with codex mcp list:

Name       Url                           Bearer Token Env Var  Status   Auth
agentmail  https://mcp.agentmail.to/mcp  -                     enabled  Not logged in

Auth reads Not logged in until you finish the browser sign-in. Inside a session, /mcp lists the AgentMail tools Codex can call.

If your AgentMail account belongs to more than one organization, ask Codex to list your organizations and select the one to work in. Signed-in sessions include tools for both.

3. Test the email tools

Start with a read. In a new session, ask:

List my AgentMail inboxes.

Codex calls the hosted server and returns your inboxes, which proves the whole path works.

Now create an inbox and send a real email. Swap in an address you check for you@example.com:

Create an AgentMail inbox with the username support-agent and send a hello email from it to you@example.com.

The email reaches that account within a couple of seconds, sent by the new @agentmail.to address.

Usernames are first come, first served, and skipping the username always works because AgentMail generates the address.

Reply to the email from your own account, then ask Codex to close the loop:

Check that inbox for a reply and summarize it.

The plugin’s skills decide how these requests run:

• $send-email drafts and delivers mail
• $check-email reads and triages it
• $manage-inboxes handles the inbox lifecycle

Codex picks the right one on its own, or you can type $ in the composer to invoke one by name. The skills treat email content as untrusted data. Compose requests create drafts rather than sending, sends require explicit or previously confirmed details, and inbox deletion requires confirming the exact address.

4. Use an API key instead of OAuth

When a browser sign-in is not possible (a shared machine, CI), configure the local bridge in ~/.codex/config.toml with an API key:

[mcp_servers.agentmail]
command = "npx"
args = ["-y", "agentmail-mcp"]
env_vars = ["AGENTMAIL_API_KEY"]

env_vars passes the variable through from the shell that starts Codex, so export AGENTMAIL_API_KEY there first. One more thing for non-interactive runs: codex exec denies tool approvals by default, and sending a message asks for one, so pass --approve-for-me to approve it automatically. The full tool catalog and the configuration for every other client are on MCP and Skills.

5. Give cloud tasks an inbox

Codex cloud tasks run in isolated containers, configured per repository, so they need an API key and the AgentMail CLI.

1. Open environment settings and create or select the environment for your repository.

2. Add AGENTMAIL_API_KEY as an environment variable. Environment variables stay set for the whole task, so the agent can authenticate while it works. Secrets are decrypted only for setup scripts and are removed before the agent starts.

3. Install the CLI in the environment’s setup script. Setup scripts run with internet access:

   npm install -g agentmail-cli

4. Agent internet access is off by default. Turn it on for the environment and add api.agentmail.to to the allowed domains so the task can reach AgentMail while it works.

A cloud task can then run agentmail commands the same way your terminal does. The commands to send, list, and reply are on Send email.

Next Steps