Guide · Updated October 2026
Email for Claude Code, Codex, OpenClaw, Hermes and Pi
Every MarkRelay deployment serves an Agent Skill at /skills/SKILL.md in the open Agent Skills format. Install it in Claude Code, Codex, OpenClaw, Hermes Agent or Pi, give the agent the API URL and a key scoped to its mailbox, and it can check, read, send, reply to and forward email from your own domain. The same file works in every one of them.
Before you start
- Create a mailbox for the agent, such as
agent@yourdomain.com, or pick the mailboxes it should work in. - In Developer → API keys, create a key with Specific mailboxes scope. The agent can never reach more than you can, and with this scope it reaches only what you pick.
- Copy the key; it starts with
sk-.
Install the skill
Pick your agent. The fastest way is to paste one message and let the agent install the skill itself: it downloads the file, asks you for the key, stores it where it belongs and checks the connection. The manual steps are underneath. Claude Code reads skills from ~/.claude/skills; Codex, OpenClaw and Pi all read ~/.agents/skills; Hermes installs straight from your deployment's URL.
The address you open MarkRelay at. The prompts and commands below fill it in; until then the prompt asks your agent to ask you.
Install the MarkRelay skill in Claude Code
Fastest: paste this into Claude Code
It installs the skill, asks you for the key, stores it, and checks the connection.
Set up the MarkRelay email skill for yourself. First ask me for my MarkRelay address (for example https://mail.example.com); below it is called MARKRELAY_URL. Then, download MARKRELAY_URL/skills/SKILL.md to ~/.claude/skills/markrelay-mail/SKILL.md. Then save MARKRELAY_API_URL=MARKRELAY_URL/openapi/v1 and MARKRELAY_API_KEY in the env section of ~/.claude/settings.json. Ask me for the key; never put it in a repository. Finally, use the skill to list the mailboxes the key can reach. Tell me if I need to restart Claude Code.Or do it yourself
1. Install the skill
mkdir -p ~/.claude/skills/markrelay-mail
curl -fsS https://<your-deployment>/skills/SKILL.md \
-o ~/.claude/skills/markrelay-mail/SKILL.md2. Give it the API URL and key
{
"env": {
"MARKRELAY_API_URL": "https://<your-deployment>/openapi/v1",
"MARKRELAY_API_KEY": "sk-..."
}
}Or export the two variables in your shell before starting claude.
3. Ask, or call /markrelay-mail
- Claude loads the skill on its own when you ask about email, or you can call it with /markrelay-mail.
- For one repository only, put the skill in .claude/skills/markrelay-mail instead.
Install the MarkRelay skill in Codex
Fastest: paste this into Codex
It installs the skill, asks you for the key, stores it, and checks the connection.
Set up the MarkRelay email skill for yourself. First ask me for my MarkRelay address (for example https://mail.example.com); below it is called MARKRELAY_URL. Then, download MARKRELAY_URL/skills/SKILL.md to ~/.agents/skills/markrelay-mail/SKILL.md. Then save MARKRELAY_API_URL=MARKRELAY_URL/openapi/v1 and MARKRELAY_API_KEY in export lines in my ~/.zshrc. Ask me for the key; never put it in a repository. Finally, use the skill to list the mailboxes the key can reach. Tell me when to restart Codex.Or do it yourself
1. Install the skill
mkdir -p ~/.agents/skills/markrelay-mail
curl -fsS https://<your-deployment>/skills/SKILL.md \
-o ~/.agents/skills/markrelay-mail/SKILL.md2. Give it the API URL and key
export MARKRELAY_API_URL=https://<your-deployment>/openapi/v1
export MARKRELAY_API_KEY=sk-...Codex passes your shell's variables to the commands it runs. If you filter them with shell_environment_policy, include both.
3. Ask, or call $markrelay-mail
- Mention the skill with $markrelay-mail, pick it from /skills, or let Codex choose it.
- ~/.agents/skills is shared with OpenClaw and Pi, so one copy serves all three.
Install the MarkRelay skill in OpenClaw
Fastest: paste this into OpenClaw
It installs the skill, asks you for the key, stores it, and checks the connection.
Set up the MarkRelay email skill for yourself. First ask me for my MarkRelay address (for example https://mail.example.com); below it is called MARKRELAY_URL. Then, download MARKRELAY_URL/skills/SKILL.md to ~/.agents/skills/markrelay-mail/SKILL.md. Then save MARKRELAY_API_URL=MARKRELAY_URL/openapi/v1 and MARKRELAY_API_KEY in skills.entries."markrelay-mail".env in ~/.openclaw/openclaw.json. Ask me for the key; never put it in a repository. Finally, use the skill to list the mailboxes the key can reach.Or do it yourself
1. Install the skill
mkdir -p ~/.agents/skills/markrelay-mail
curl -fsS https://<your-deployment>/skills/SKILL.md \
-o ~/.agents/skills/markrelay-mail/SKILL.md2. Give it the API URL and key
{
skills: {
entries: {
"markrelay-mail": {
env: {
MARKRELAY_API_URL: "https://<your-deployment>/openapi/v1",
MARKRELAY_API_KEY: "sk-...",
},
},
},
},
}The Gateway runs as a service, so set the variables here rather than in your shell.
3. Ask, or call /markrelay-mail
- OpenClaw also reads ~/.openclaw/skills. The new skill appears on your next message; no restart needed.
- Ask from any channel OpenClaw is connected to, such as Telegram or WhatsApp: “anything urgent in support@ today?”
Install the MarkRelay skill in Hermes Agent
Fastest: paste this into Hermes Agent
It installs the skill, asks you for the key, stores it, and checks the connection.
Set up the MarkRelay email skill for yourself. First ask me for my MarkRelay address (for example https://mail.example.com); below it is called MARKRELAY_URL. Then, run: hermes skills install MARKRELAY_URL/skills/SKILL.md. Then save MARKRELAY_API_URL=MARKRELAY_URL/openapi/v1 and MARKRELAY_API_KEY in ~/.hermes/.env, and list both in terminal.env_passthrough in ~/.hermes/config.yaml. Ask me for the key; never put it in a repository. Finally, use the skill to list the mailboxes the key can reach.Or do it yourself
1. Install the skill
hermes skills install https://<your-deployment>/skills/SKILL.md2. Give it the API URL and key
MARKRELAY_API_URL=https://<your-deployment>/openapi/v1
MARKRELAY_API_KEY=sk-...terminal:
env_passthrough: [MARKRELAY_API_URL, MARKRELAY_API_KEY]Hermes keeps secrets in ~/.hermes/.env and forwards only the variables you list to its terminal tool.
3. Ask, or call /markrelay-mail
- Hermes installs the skill into ~/.hermes/skills and makes it a slash command: /markrelay-mail check support@ for new mail.
- Install it again after you update MarkRelay to pick up the latest skill.
Install the MarkRelay skill in Pi
Fastest: paste this into Pi
It installs the skill, asks you for the key, stores it, and checks the connection.
Set up the MarkRelay email skill for yourself. First ask me for my MarkRelay address (for example https://mail.example.com); below it is called MARKRELAY_URL. Then, download MARKRELAY_URL/skills/SKILL.md to ~/.agents/skills/markrelay-mail/SKILL.md. Then save MARKRELAY_API_URL=MARKRELAY_URL/openapi/v1 and MARKRELAY_API_KEY in export lines in my ~/.zshrc. Ask me for the key; never put it in a repository. Finally, use the skill to list the mailboxes the key can reach. Tell me when to restart pi.Or do it yourself
1. Install the skill
mkdir -p ~/.agents/skills/markrelay-mail
curl -fsS https://<your-deployment>/skills/SKILL.md \
-o ~/.agents/skills/markrelay-mail/SKILL.md2. Give it the API URL and key
export MARKRELAY_API_URL=https://<your-deployment>/openapi/v1
export MARKRELAY_API_KEY=sk-...Export the two variables in your shell before starting pi.
3. Ask, or call /skill:markrelay-mail
- Pi also reads ~/.pi/agent/skills, and loads the skill when a task matches.
- To call it with /skill:markrelay-mail, turn on skill commands in /settings.
What it looks like
Ask in plain language. The skill tells the agent which calls to make, how to page through results, and what never to retry.
›Check agent@acme.com for unread mail. Answer password-reset requests yourself and flag anything else for me.●Using skill markrelay-mail$curl -s -H "Authorization: Bearer $MARKRELAY_API_KEY" "$MARKRELAY_API_URL/emails?mailbox=agent@acme.com&read=false"2 unread: “Reset my password please” (Sam Patel) · “Where is order #4830?” (Elena García)$curl -s -X POST … "$MARKRELAY_API_URL/emails/b68419a2-…/reply" -d '{"text":"Hi Sam, I have sent a fresh reset link…"}'{"id":"528a8469-74ee-4dc4-8023-0d3882699ad2"}●Replied to Sam Patel with a fresh reset link. Elena García is asking about order #4830, which needs a tracking lookup, so I left it unread for you.
Things to ask
- “Check support@acme.com for mail since 9am and summarize what needs a reply.”
- “Reply to the latest message from Priya Nair: the export fix ships today.”
- “Send ./reports/october.pdf to billing@brightpath.io from billing@acme.com.”
- “Forward every unread invoice email in billing@ to accounts@acme.com, then archive them.”
- “Draft replies to new sales@ inquiries and leave them for me to review.”
Keep it safe
- Give each agent its own key with the narrowest scope that works, and keep it out of repositories.
- When the agent installs the skill for you, the key you paste stays in that conversation's history. If you would rather it did not, use the manual steps.
- Ask the agent to draft and wait for your approval before it sends anything sensitive.
The full list, including what the skill tells agents never to retry, is in the agent skill reference.
Why a mailbox of its own instead of your Gmail: see give an agent one mailbox, not your whole inbox.
Other agents
Claude, ChatGPT, Cursor and other MCP clients connect to your deployment's MCP server with a sign-in instead of a skill. Agents without either can use the same HTTP API through your deployment's /llms.txt or OpenAPI document; see what each deployment serves.
One page per agent
Common questions
Which AI agents work with MarkRelay?
Claude Code, Codex, OpenClaw, Hermes Agent and Pi load the skill your deployment serves at /skills/SKILL.md, which follows the open Agent Skills format. Any other agent that can make HTTP requests can use the same API through the deployment's llms.txt or OpenAPI document.
Can I ask OpenClaw or Hermes about my email from my phone?
Yes. Both run as personal assistants you can message from chat apps such as Telegram or WhatsApp. Once the skill and key are set up, ask them to check a mailbox, summarize new mail or send a reply.
Is there an MCP server?
Yes. Every deployment is a remote MCP server at /mcp; Claude, ChatGPT, Cursor and other MCP clients connect with OAuth, see the MCP server guide. The skill is the other way in: the agent calls the plain HTTP API with curl or its own HTTP tool, so there is no server to run next to the agent.
Can the agent read every mailbox?
Only the mailboxes its key reaches. Create a key with Specific mailboxes scope, for example agent@ only, and the agent cannot list or read anything else.
Does the skill stay up to date?
Your deployment builds the skill for its own API URL and version. After you update MarkRelay, download SKILL.md again to pick up any changes.
Related: Agent skill reference, Email API and email for AI agents.