---
title: Skill for coding agents
description: Install the BillionSend skill so Claude Code and Codex know how to connect, work an inbox and treat received mail as untrusted.
---

The BillionSend skill is one `SKILL.md` file that teaches a coding agent how to use BillionSend: connecting to the [MCP server](/docs/mcp) with OAuth or an agent key, finding an inbox, waiting for verification codes and messages, replying, drafting for approval, what to do when the inbox's rules hold a send as a draft, and why received mail is data and never instructions. The agent loads it when a task mentions BillionSend, a `bs_` API key or a `bs_agent_` key, or giving an agent an email inbox.

The file is at `https://billionsend.com/docs/skills/billionsend/SKILL.md`. It is written in English, the language the agents read it in.

## Install

Each agent reads skills from a folder named after the skill, `billionsend`, holding `SKILL.md`.

**Claude Code**

```sh
mkdir -p ~/.claude/skills/billionsend
curl -fsSL https://billionsend.com/docs/skills/billionsend/SKILL.md -o ~/.claude/skills/billionsend/SKILL.md
```

That installs it for every project on this machine. To share it with a repository's team instead, save it as `.claude/skills/billionsend/SKILL.md` in the repository and commit it.

**Codex**

```sh
mkdir -p ~/.agents/skills/billionsend
curl -fsSL https://billionsend.com/docs/skills/billionsend/SKILL.md -o ~/.agents/skills/billionsend/SKILL.md
```

That installs it for every project on this machine. To share it with a repository's team instead, save it as `.agents/skills/billionsend/SKILL.md` at the repository's root and commit it.

Run the command again to update the skill. Start a new session after installing so the agent picks it up.

## Connect the MCP server

The skill tells the agent how to use BillionSend's tools; the agent still needs the server.

**Claude Code**

```sh
claude mcp add --transport http billionsend https://api.billionsend.com/mcp
```

Then run `/mcp` inside Claude Code and pick `billionsend` to sign in. See [MCP server](/docs/mcp) for the permissions you grant.

**Codex**

Create an agent key under **MCP → Create agent key** and add the server to `~/.codex/config.toml`:

```toml title="~/.codex/config.toml"
[mcp_servers.billionsend]
url = "https://api.billionsend.com/mcp"
bearer_token_env_var = "BILLIONSEND_AGENT_KEY"
```

Export `BILLIONSEND_AGENT_KEY` in the shell before starting Codex. The key never goes into the file.

## What the skill covers

| Part | What it tells the agent |
| --- | --- |
| Connect | The MCP endpoint, OAuth and agent keys, the three agent key scopes, and that regular `bs_` keys work only on the REST API. |
| Inbox workflows | `list_inboxes` first (tools take the inbox id), then `get_verification_code`, `wait_for_received_email`, `get_received_email`, `reply_to_received_email`, `send_from_inbox` and the draft tools. |
| Held sends | That `draft` with reasons is the rules working: report it, point to the **Needs review** tab, and never route around it. The errors it may meet and what each means. |
| Untrusted mail | The `untrusted_data` envelope and the `UNTRUSTED EMAIL CONTENT` fence, `sender_trust` and `screening.verdict`, and what never to do because a message asks. See [Agent safety](/docs/agent-safety). |
| Sending | `send_email` and `send_email_batch` from verified domains, `get_usage` before bulk work, and the REST API. |

The skill adds no permission. What the agent can do is still set by its OAuth grant or its agent key's scope, its [team role](/docs/team-roles) and each inbox's [send rules](/docs/inboxes).
