# Codex

Codex is OpenAI’s open-source AI coding agent, available as a CLI tool, desktop app, IDE extension, and cloud agent at chatgpt.com/codex. This guide shows how to connect it to Mailtrap using the [Mailtrap MCP server](https://docs.mailtrap.io/guides/ai-powered-integrations/mcp-server). 

Once configured, Codex can help you with email sending operations, including email logs, statistics, email templates, and sending domain management. Also, you can use sandbox operations - all through natural language prompts. 

### Prerequisites

* Node.js 16+ installed on your machine (20 LTS recommended; mcp-mailtrap runs as a Node.js command-line utility)
* Codex CLI installed via `npm i -g @openai/codex` or `brew install --cask codex`
* An OpenAI account (sign in with your ChatGPT account, or set `OPENAI_API_KEY`)

### Step 1: Set up Mailtrap

In your Mailtrap account, you just need to generate the API token. Go to Settings → API Tokens → Add Token and copy your token. The rest is handled by the MCP. 

### Step 2: Add the Mailtrap MCP server to Codex

The fastest way is the Codex CLI’s built-in mcp add command:

`codex mcp add mailtrap -- npx -y mcp-mailtrap`

This registers the Mailtrap MCP server in your Codex config. To add it manually instead, open `~/.codex/config.toml` and add:

```bash
[mcp_servers.mailtrap]
command = "npx"
args = ["-y", "mcp-mailtrap"]
[mcp_servers.mailtrap.env]
MAILTRAP_API_TOKEN = "your_mailtrap_api_token"
DEFAULT_FROM_EMAIL = "your_sender@example.com"
MAILTRAP_ACCOUNT_ID = "your_account_id"
MAILTRAP_TEST_INBOX_ID = "your_test_inbox_id"ome code
```

For a project-scoped setup, place a `codex.toml` file with the same MCP block in your project root instead.

### Step 3: Insert your Mailtrap credentials

If you used `codex mcp add`, open `~/.codex/config.toml` and add the `env` block under `[mcp_servers.mailtrap]`. Replace the placeholder values:

| MAILTRAP\_API\_TOKEN      | Required for all operations; copy from Sending Settings → API Tokens → Add Token |
| ------------------------- | -------------------------------------------------------------------------------- |
| DEFAULT\_FROM\_EMAIL      | Required for sending; must be on your verified sending domain                    |
| MAILTRAP\_ACCOUNT\_ID     | Required for template management; find under Settings → Account Settings         |
| MAILTRAP\_TEST\_INBOX\_ID | Required for sandbox operations; visible in your sandbox inbox URL               |

Codex reads standard env vars, so exporting `MAILTRAP_API_TOKEN` in your shell profile works as expected.

### Step 4: Configure tool approval modes

Codex lets you control how much autonomy the agent has per MCP tool. By default, Codex asks for confirmation before executing any MCP tool call. You can adjust this per tool:

```bash
[mcp_servers.mailtrap.tools.send_email]
approval_mode = "approve"
[mcp_servers.mailtrap.tools.list_sandbox_messages]
approval_mode = "auto"
```

<figure><img src="https://365478608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgkNigAKiqQtQub1GOdjY%2Fuploads%2F2t4r4QBh83Mh8sRGG8x1%2FCodex%20function%20approval.png?alt=media&#x26;token=c7a23bf9-1593-4cb3-a2f4-200b08933195" alt=""><figcaption></figcaption></figure>

Available modes:

| approve | Codex shows the parameters and waits for your confirmation (default, safest for sending)               |
| ------- | ------------------------------------------------------------------------------------------------------ |
| auto    | Codex executes the tool without asking (useful for read-only operations like listing sandbox messages) |

This gives you fine-grained control: let the agent freely inspect your sandbox inbox, but require explicit approval before sending any email.

### Step 5: Add Mailtrap to your project through Codex

Launch Codex and type a natural-language prompt:

```bash
Add Mailtrap email sending to this Node.js project using their API. Use the API token from my environment variables.
```

Codex runs the action, makes the necessary updates, verifies the server file, and confirms the acitons.

<figure><img src="https://365478608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgkNigAKiqQtQub1GOdjY%2Fuploads%2F5YrpfOOkV1UMXH80Bu0b%2FCodex%20add%20Mailtrap%20to%20project.png?alt=media&#x26;token=3ce2739f-ff29-4ab9-a091-882fd3f5e0e6" alt=""><figcaption></figcaption></figure>

#### More prompt examples

Inspect sandbox messages:

```bash
Show me the last 5 emails in my Mailtrap sandbox.
```

<figure><img src="https://365478608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgkNigAKiqQtQub1GOdjY%2Fuploads%2FrxNEYiLUCf0eLjp4UCa1%2FCodex%20list%20inbox%20messages.png?alt=media&#x26;token=53887b1a-632f-4195-8ff4-b42254ff80c4" alt=""><figcaption></figcaption></figure>

Manage templates:

```bash
List all my email templates and show me the subject line of each.
```

<figure><img src="https://365478608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgkNigAKiqQtQub1GOdjY%2Fuploads%2FqVnlYG4Jq3yvwICLBAax%2FCodex%20list%20all%20my%20templates.png?alt=media&#x26;token=4ddad5f4-3b33-46cb-afac-5a2a00fda733" alt=""><figcaption></figcaption></figure>

Get sending stats:

```bash
Pull delivery stats for yourdomain.example
```

<figure><img src="https://365478608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgkNigAKiqQtQub1GOdjY%2Fuploads%2FPtNZWWgBkcQdobv430sC%2FCodex%20get%20sending%20stats.png?alt=media&#x26;token=5878f37b-61d6-4adc-87ca-c694a1d81029" alt=""><figcaption></figcaption></figure>

Codex gives you the stats, including a quick overview and commentary. You can dig deeper for email performance within an email category or provider or check the email logs.&#x20;

### Step 6: Use Codex in headless mode for CI/CD

Codex’s quiet mode runs prompts non-interactively, which is useful for automated email testing in CI/CD pipelines:

```bash
codex -q --json "Send a test email to qa@example.com with subject
  'CI build #${BUILD_NUMBER} complete' and check the sandbox
  inbox for delivery confirmation."
```

The `--json` flag returns structured output, making it easy to parse results in your pipeline scripts.

### Use Cases

* Trigger a test email to Mailtrap’s Email Sandbox while reviewing email-sending code and inspect message content, headers, and metadata without leaving the terminal
* Ask Codex to scaffold Mailtrap into a new project: it installs the SDK, writes API calls, and sets up environment variables based on your MCP config
* Iterate on email templates mid-session by fetching the current template list, editing subject lines or body copy, and pushing updates; all through prompts
* Verify that a transactional trigger (password reset, order confirmation) sends the correct content by prompting Codex to fire the email and inspect the result in sandbox

### Supported Functionality

* Email sending operations
* Email logs (debug delivery)
* Sending statistics&#x20;
* Sandbox operations
* Template operations&#x20;
* Sending domains management

### Technical notes

* Codex applies a 10-second default startup timeout for MCP servers (configurable via startup\_timeout\_sec in the TOML config). If npx needs to download mcp-mailtrap for the first time, run npx -y mcp-mailtrap once manually to cache the package.
* Tool-call timeout defaults to 60 seconds (tool\_timeout\_sec). This is more than enough for Mailtrap API operations but worth knowing if you’re chaining multiple calls.
* In Full Auto mode, Codex disables network access in the sandbox for security. MCP tool calls still work because they run through the MCP protocol outside the sandbox. However, any code Codex writes and executes that tries to call Mailtrap’s API directly will be blocked. Use Suggest or Auto Edit mode for live API testing.
* Project-level config (codex.toml in the project root) merges with global config (\~/.codex/config.toml). If both define the Mailtrap MCP server, the project-level definition takes precedence.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mailtrap.io/guides/ai-powered-integrations/codex.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.