Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

Skill for coding agents

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 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.

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.

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 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 for the permissions you grant.

Create an agent key under MCP → Create agent key and add the server to ~/.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.
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 and each inbox’s send rules.

Was this page helpful?