OpenCode

OpenCode Integration with Mailtrap

OpenCode is an open-source AI coding agent that runs in the terminal, as a desktop app, or inside IDE extensions.

This guide shows how to connect it to Mailtrap using the Mailtrap MCP server, giving your agent the ability to add email sending to your project, inspect sandbox inboxes, manage templates, and check delivery stats; all from natural-language prompts.

Prerequisites

• A Mailtrap account with a configured sending domain (takes ~5 minutes)

• Node.js installed on your machine (mcp-mailtrap runs as a Node.js command-line utility)

• OpenCode installed — via brew install anomalyco/tap/opencode, npm i -g opencode-ai@latest, or the install script

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 OpenCode

Open or create an opencode.json file in your project root. Add the Mailtrap MCP server under the mcp key:

{
  "mcp": {
    "mailtrap": {
      "type": "local",
      "command": ["npx", "-y", "mcp-mailtrap"],
      "environment": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      },
      "enabled": true
    }
  }
}

For a global setup (available across all projects), place the same file at ~/.config/opencode/opencode.json instead.

Step 3: Insert your Mailtrap credentials

Replace the placeholder values in opencode.json:

MAILTRAP_API_TOKEN	Required for all operations; copy from Sending Domains → Integration → API
DEFAULT_FROM_EMAIL	Required for sending; must be an address 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

OpenCode also supports environment variable substitution via {env:VAR_NAME} syntax. If you’d rather keep credentials out of the config file, set them as environment variables and reference them like this:

{
  "mcp": {
    "mailtrap": {
      "type": "local",
      "command": ["npx", "-y", "mcp-mailtrap"],
      "environment": {
        "MAILTRAP_API_TOKEN": "{env:MAILTRAP_API_TOKEN}",
        "DEFAULT_FROM_EMAIL": "{env:DEFAULT_FROM_EMAIL}",
        "MAILTRAP_ACCOUNT_ID": "{env:MAILTRAP_ACCOUNT_ID}",
        "MAILTRAP_TEST_INBOX_ID": "{env:MAILTRAP_TEST_INBOX_ID}"
      },
      "enabled": true
    }
  }
}

Note that the most common approach to setting environment variables is ~/.zshrc for API keys you use across multiple tools. If you’re working with different projects and credentials, the better approach is .env + direnv. For instance, if you’re on macOS with zsh, check the options below:

• For current terminal sessions only:

 export OPENAI_API_KEY="sk-..."

Run this before starting OpenCode. It’s gone when the terminal closes.

• Persistent (accross all sessions):

Add the export line to ~/.zshrc:

export OPENAI_API_KEY="sk-..."

• Per-project (without polluting your shell):

Put vars in a .env file at the project root and load them with a tool like direnv, or source the file manually:

# .env
OPENAI_API_KEY="sk-..."
# then in terminal
source .env

• Verify a variable is set:

echo $OPENAI_API_KEY

Step 4: Verify the MCP server is active

Launch OpenCode in your project directory:

opencode

Once the TUI loads, the Mailtrap MCP server starts automatically. OpenCode discovers all tools exposed by mcp-mailtrap and makes them available to the agent. You can confirm by asking:

What Mailtrap tools do you have access to?

The agent should list the available tools — send email, list sandbox messages, manage templates, and others.

Step 5: Add Mailtrap to your project through OpenCode

Type a natural-language prompt directly in the OpenCode TUI. For example:

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

OpenCode runs the action, makes the necessary updates, and confirms the addition/update.

More prompt examples

Inspect sandbox messages:

Show me the last 5 emails in my Mailtrap sandbox inbox.

Manage templates:

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

Get sending stats:

Pull delivery stats for yourdomain.example

Step 6: Use OpenCode in headless mode for CI/CD

OpenCode’s run command lets you execute prompts non-interactively, which is useful for automated email testing in CI/CD pipelines:

opencode run "Send a test email to [email protected] with subject 'CI build
#$BUILD_NUMBER complete' and check the sandbox inbox for delivery confirmation."

This runs the prompt, executes the MCP tool calls, and exits; no interactive session required.

Confirmed in the sandbox.

Use cases

• Bulk template actions - List all templates, review them for consistency or branding issues, then batch-update subjects, categories, or markup across templates.

• Delivery forensics - "Why didn't user X get their email?" → query list-email-logs filtered by recipient, check status/bounce/rejection events, pull the raw EML via get-email-log-message, diagnose the root cause.

• Domain setup assistant - create-sending-domain, then get-sending-domain with include_setup_instructions to get DNS records, and have AI explain exactly what to add in your DNS provider (Cloudflare, Route53, etc.).

• Incident triage - "Are emails going out?" → check get-sending-stats for the last hour, filter list-email-logs by status: not_delivered, and surface any spike in bounces or rejections.

• Opt-out audit - Filter email logs by status: opted_out to understand unsubscribe patterns and correlate with specific categories or time periods.

• Weekly email health report - Pull get-sending-stats broken down by date for the past week, have the AI summarize trends in delivery rates, opens, clicks, bounces, and flag anomalies.

Supported functionality

• Email sending operations

• Email logs (debug delivery)

• Sending statistics

• Sandbox operations

• Template operations

• Sending domains management

Technical notes

• OpenCode applies a 30-second timeout when initializing MCP servers at startup. If your network is slow and npx needs to download mcp-mailtrap for the first time, the server may time out silently. Run npx -y mcp-mailtrap once manually to cache the package before launching OpenCode.

• The {env:VAR_NAME} syntax in opencode.json resolves at startup, not at tool-call time. If you change an environment variable, restart OpenCode to pick up the new value.

• Project-level config (opencode.json in the project root) takes precedence over global config (~/.config/opencode/opencode.json). If you define the Mailtrap MCP server in both, the project-level definition wins.