# Send & Receive Emails with opencode (/integrations/frameworks/opencode)

<!-- agent-signals: reading_time_min: 2 · est_tokens: 897 · updated: 2026-09-06 -->
Related: [Send & Receive Emails with Claude Cowork](/integrations/frameworks/claude-cowork.md), [Send & Receive Emails with Claude Code](/integrations/frameworks/claude-code.md), [Send & Receive Emails with OpenAI Codex](/integrations/frameworks/codex.md), [Send & Receive Emails with OpenClaw](/integrations/frameworks/openclaw.md), [Send & Receive Emails with Grok](/integrations/frameworks/grok.md), [Send & Receive Emails with Manus](/integrations/frameworks/manus.md)



# Connect opencode to AgentMail

Add AgentMail's hosted MCP server to opencode's config and it gets `@agentmail.to` inboxes to send, receive, and reply from, authenticated by an API key header or an OAuth sign-in.

## Do this

1. Add the server to `opencode.json` in the project root, or `~/.config/opencode/opencode.json` globally:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agentmail": {
      "type": "remote",
      "url": "https://mcp.agentmail.to/mcp",
      "enabled": true,
      "headers": {
        "x-api-key": "{env:AGENTMAIL_API_KEY}"
      }
    }
  }
}
```

2. Export `AGENTMAIL_API_KEY` (from `https://console.agentmail.to/dashboard/api-keys`) in the environment opencode starts from.
3. Prompt:

```text
Create an AgentMail inbox and send a hi email from it to you@example.com.
```

## Facts

* Remote MCP entries in `opencode.json` take `"type": "remote"`, a `url`, optional `headers`, and `"enabled": true`.
* `{env:AGENTMAIL_API_KEY}` substitutes the environment variable into the config. An unset variable becomes an empty string, which fails auth with `401`.
* OAuth alternative: drop `headers` and run `opencode mcp auth agentmail`. opencode handles the sign-in with dynamic client registration and stores tokens in `~/.local/share/opencode/mcp-auth.json`. `opencode mcp logout agentmail` removes them.
* `opencode mcp list` shows every configured server and its auth status.
* The endpoint is exactly `https://mcp.agentmail.to/mcp`. Full tool catalog and OAuth details: [MCP and Skills](/integrations/mcp-and-skills).
* Creating an inbox without a username lets AgentMail generate an available one. A taken username makes `create_inbox` return `403` with up to 3 available variants in `suggestions`.

## Not supported

* The API-key path needs a valid key in the header. To connect without one, drop `headers` and use `opencode mcp auth agentmail`.

## Errors

| Error               | Status | Cause                                                                                    | Fix                                                                              |
| ------------------- | ------ | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `401` on every call | 401    | `AGENTMAIL_API_KEY` unset (substituted as empty) or invalid, or OAuth sign-in unfinished | Export the key before starting opencode, or re-run `opencode mcp auth agentmail` |
| `404` on every call | 404    | Incorrect server URL                                                                     | Set the URL to exactly `https://mcp.agentmail.to/mcp`                            |
| `resource_taken`    | 403    | The requested inbox username belongs to another organization                             | Retry with one of the up to 3 variants in `suggestions`                          |
| `already_exists`    | 403    | An inbox with the requested username already exists in the organization                  | Retry with a username from `suggestions`, or use the existing inbox              |

## Verify

Run `opencode mcp list` (the agentmail server appears with its auth status), then prompt `List my AgentMail inboxes`. Success is opencode calling `list_inboxes` and returning the addresses.

## Related

* [MCP and Skills](/integrations/mcp-and-skills): the full tool catalog, OAuth details, and skills.
* [Agent safety](/advanced/safety): treat inbound mail as untrusted and confirm sends before the agent acts.