# Give OpenCode its own email address

OpenCode can have its own email address, such as `ada@botmail.pro`. Paste one
prompt to claim a Botmail mailbox, run
`opencode mcp add botmail --global --url https://botmail.pro/mcp`, and sign
in from `/mcps`. Your OpenCode agents can then read, send, reply to and wait
for email at their own address.

## Why OpenCode needs its own address

OpenCode runs as a background service with sessions you can leave running.
An inbox lets those sessions talk to the outside world:

- **Report back.** "Bisect the regression and email me the bad commit" gives
  you an answer in your inbox instead of a session you have to find later.
- **Follow a thread.** It can read the vendor's reply about your API quota
  and answer in the same conversation, from any session or agent.
- **Receive codes.** It can sign up for a service you approve and read the
  verification email. See
  [verification emails](https://botmail.pro/guides/ai-agent-verification-emails).
- **Draft for review.** It writes outreach as a draft and gives you a link to
  approve it.

## 1. Claim a mailbox

Paste this into OpenCode:

```text
Read https://botmail.pro/skill.md and claim a mailbox for yourself. Send the invite to my email, then wait for me to approve it.
```

OpenCode fetches the instructions, solves a small proof-of-work challenge in
the shell and claims an address. It asks for your email if it doesn't know
it. Open the email from Botmail, sign in with GitHub or Google and accept.
Unapproved mailboxes are deleted after 24 hours.

## 2. Add Botmail to OpenCode

Add the server for every project:

```sh
opencode mcp add botmail --global --url https://botmail.pro/mcp
opencode mcp list
```

Leave out `--global` to add it to the current project's config instead. The
command writes this, which you can also add to
`~/.config/opencode/opencode.json` (or a project `opencode.json`) yourself:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "botmail": { "type": "remote", "url": "https://botmail.pro/mcp" }
    }
  }
}
```

OpenCode V2 groups servers under `mcp.servers`. An older V1 config with
`botmail` directly under `mcp` still loads in V2.

Remote servers use OAuth by default, and OpenCode registers itself with
Botmail, so there's no client ID. When `opencode mcp list` shows
`needs authentication`, open OpenCode, run `/mcps`, select botmail and sign
in. The CLI can start the same flow:

```sh
opencode mcp auth botmail
```

When it's done, the list shows:

```text
✓ botmail  connected
```

OpenCode keeps the OAuth credentials outside your config files, so a project
`opencode.json` with Botmail in it is safe to commit. Each teammate signs in
for themselves.

### How the tools appear

OpenCode names MCP tools `<server>_<tool>`, so Botmail's tools become
`botmail_check_inbox`, `botmail_send_email` and so on. In the default Code
Mode, agents call them as `tools.botmail.check_inbox(...)`.

### Use an API key instead

Turn off OAuth for the server and send the key your agent saved when it
claimed the mailbox. `{env:NAME}` reads it from your environment:

```json
{
  "mcp": {
    "servers": {
      "botmail": {
        "type": "remote",
        "url": "https://botmail.pro/mcp",
        "oauth": false,
        "headers": { "Authorization": "Bearer {env:BOTMAIL_KEY}" }
      }
    }
  }
}
```

OpenCode doesn't expand `$BOTMAIL_KEY` in JSON strings; use the `{env:...}`
form.

## 3. Approve access

Your browser opens a Botmail page. Sign in with GitHub or Google and choose:

- **Permissions:** Read mail, Send mail and Manage (mailboxes, keys, webhooks
  and settings).
- **Mailboxes:** all of them, including ones you create later, or only the
  ones you tick.

Press Allow. You can revoke access at any time, and
`opencode mcp logout botmail` removes the stored credentials.

## Prompts to try

```text
Bisect the failing build between v1.4.0 and main. When you find the commit, email me at you@example.com with the hash and a one-line explanation.
```

```text
Read the latest thread from Acme support about our API quota and draft a reply asking for a temporary increase. Give me the review link.
```

```text
Sign up for the Acme status page with your Botmail address and confirm the subscription email.
```

```text
Use wait_for_mail to watch your inbox and tell me as soon as the release approval from Sam arrives.
```

For first contact with someone new, ask for a draft. Mail to new recipients
is checked for spam and phishing, and new accounts can email 25 new
recipients a day.

## Optional: install Botmail as a skill

OpenCode loads global skills from `~/.config/opencode/skills`, and also reads
`~/.claude/skills` and `~/.agents/skills`. Botmail's [skill.md](https://botmail.pro/skill.md)
has skill front matter, so it installs as-is:

```sh
mkdir -p ~/.config/opencode/skills/botmail
curl -s https://botmail.pro/skill.md -o ~/.config/opencode/skills/botmail/SKILL.md
```

The folder name sets the skill ID, `botmail`. Mention `@botmail` in a prompt
to load it yourself.

## Troubleshooting

- **Still "needs authentication" after signing in.** Run `/mcps` and connect
  botmail again, or run `opencode mcp auth botmail`.
- **Signed in to the wrong account.** Run `opencode mcp logout botmail`, then
  sign in again.
- **A project config "loses" settings.** A project `opencode.json` that also
  defines `botmail` replaces the whole server entry from your global config,
  so repeat every field you need in it.
- **You want it configured but not connected.** Add `"disabled": true` to the
  server entry.

Using other clients as well? See [Email MCP server](https://botmail.pro/guides/email-mcp-server)
and [Email for AI agents](https://botmail.pro/ai-agent-email).

## Questions

### How do I add a remote MCP server to OpenCode?

Run opencode mcp add botmail --global --url https://botmail.pro/mcp. In OpenCode V2 the server is saved under mcp.servers with type remote. Leave out --global to add it to the current project only.

### How do I sign in to an OAuth MCP server in OpenCode?

When opencode mcp list shows needs authentication, run /mcps in OpenCode, select the server and sign in, or run opencode mcp auth botmail from your terminal.

### Can OpenCode use an API key instead of OAuth?

Yes. Set oauth to false on the server and add a headers entry with Authorization set to Bearer {env:BOTMAIL_KEY}, so the key is read from your environment.

---

Source: https://botmail.pro/guides/opencode-email
Agent instructions: https://botmail.pro/skill.md
All guides: https://botmail.pro/llms.txt