Give Codex an email inbox on your own domain
Create agent@yourdomain.com in your own Cloudflare account, give Codex a key that reaches only that mailbox, and install the MarkRelay skill. Codex can then read, search, send and reply from that address, and nothing else.
Facts checked
In short
Deploy MarkRelay to your Cloudflare account, create agent@yourdomain.com, create an API key scoped to that one mailbox, and install the MarkRelay skill in Codex. Codex loads it from ~/.agents/skills/markrelay-mail; mention it with $markrelay-mail, pick it from /skills, or let Codex choose it. Codex can then check, read, search, send, reply to and forward mail from that address, and nothing else. Mail stays in your own Cloudflare D1 and R2, and MarkRelay charges nothing per inbox or per message.
What Codex can do with its mailbox
| Capability | MarkRelay |
|---|---|
| List the mailboxes its key can use | GET /mailboxes |
| Check and search mail | By folder, read state, sender, subject, text and date |
| Read a message and its attachments | Yes |
| Send from its own address | Up to 50 recipients, 5 MiB per message |
| Reply and forward in the same thread | Yes |
| Mark read, star, move to a folder | Yes |
| Reach other mailboxes | No: the key reaches only the mailboxes you grant |
| Hear about new mail at once | Signed webhook to your own runner |
| How it connects | Agent Skill + HTTP API, or the remote MCP server |
| Needs | A domain on Cloudflare DNS; Workers Paid to send |
List the mailboxes its key can use
- MarkRelay
- GET /mailboxes
Check and search mail
- MarkRelay
- By folder, read state, sender, subject, text and date
Read a message and its attachments
- MarkRelay
- Yes
Send from its own address
- MarkRelay
- Up to 50 recipients, 5 MiB per message
Reply and forward in the same thread
- MarkRelay
- Yes
Mark read, star, move to a folder
- MarkRelay
- Yes
Reach other mailboxes
- MarkRelay
- No: the key reaches only the mailboxes you grant
Hear about new mail at once
- MarkRelay
- Signed webhook to your own runner
How it connects
- MarkRelay
- Agent Skill + HTTP API, or the remote MCP server
Needs
- MarkRelay
- A domain on Cloudflare DNS; Workers Paid to send
Its own address
agent@yourdomain.com, on your domain and in your Cloudflare account.
One mailbox, one key
The key reaches that mailbox and nothing else.
Installs as a skill
Codex loads the skill your deployment serves at /skills/SKILL.md.
People stay in the loop
Review and take over the agent's threads in webmail.
Set it up in Codex
1. Deploy MarkRelay with the Deploy to Cloudflare button and add your domain. 2. Create a mailbox for the agent, such as agent@yourdomain.com. 3. In Developer → API keys, create a key with Specific mailboxes scope and pick only that mailbox. 4. Install the skill your deployment serves at /skills/SKILL.md and give the agent the API URL and key.
The quickest way is to paste one message into Codex: it downloads the skill, asks you for the key, stores it and checks the connection.
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 to ask Codex
Talk to the agent in plain language. The skill tells it which calls to make, how to page through results, and never to retry a send without checking first.
- “$markrelay-mail check agent@ for anything from GitHub.”
- “Send the test report in ./reports to qa@acme.com.”
- “Reply to the last email from Sara with the deploy URL.”
- “List unread mail in support@ and group it by topic.”
›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.
Why not your personal Gmail
A key scoped to agent@yourdomain.com cannot open any other mailbox, so Codex never sees your personal or customer mail. The agent sends from your own domain, and its mail stays in your own Cloudflare account.
Everything the agent sends appears in MarkRelay's webmail with an API badge, so a person can review a thread, take over or reply by hand.
How it connects to Codex
The skill is a SKILL.md file in the open Agent Skills format. Codex runs MarkRelay's HTTP API with curl and reads MARKRELAY_API_URL and MARKRELAY_API_KEY from your shell environment.
~/.agents/skills is shared with OpenClaw and Pi, so one copy of the skill serves all three. If you filter environment variables with shell_environment_policy, include both.
MarkRelay, AgentMail or your own Gmail
Three ways to give an agent email, compared on what matters for an agent.
| Feature | MarkRelayLicense from $99/yr | AgentMailHosted inbox API | Your GmailPersonal account |
|---|---|---|---|
| The agent's address | agent@yourdomain.com | On AgentMail's domain, or yours on paid plans | Your personal address |
| Where mail is stored | Your Cloudflare D1 and R2 | AgentMail's cloud | |
| What the agent's key reaches | Only the mailboxes you grant | The inboxes in your AgentMail account | Whatever its OAuth scope allows in your mailbox |
| Price for more agents | No per-inbox fee | 3 inboxes free, then plans from $20/mo | One Google account per address |
| People review in webmail | Yes | — | Yes |
| Installs as an Agent Skill | Yes | — | — |
| MCP server | Yes | Yes | — |
The agent's address
- MarkRelay
- agent@yourdomain.com
- AgentMail
- On AgentMail's domain, or yours on paid plans
- Your Gmail
- Your personal address
Where mail is stored
- MarkRelay
- Your Cloudflare D1 and R2
- AgentMail
- AgentMail's cloud
- Your Gmail
What the agent's key reaches
- MarkRelay
- Only the mailboxes you grant
- AgentMail
- The inboxes in your AgentMail account
- Your Gmail
- Whatever its OAuth scope allows in your mailbox
Price for more agents
- MarkRelay
- No per-inbox fee
- AgentMail
- 3 inboxes free, then plans from $20/mo
- Your Gmail
- One Google account per address
People review in webmail
- MarkRelay
- Yes
- AgentMail
- —
- Your Gmail
- Yes
Installs as an Agent Skill
- MarkRelay
- Yes
- AgentMail
- —
- Your Gmail
- —
MCP server
- MarkRelay
- Yes
- AgentMail
- Yes
- Your Gmail
- —
AgentMail facts from agentmail.to/pricing. “—” means it does not say.
Common questions
How do I give Codex its own email address?
Create a mailbox such as agent@yourdomain.com in MarkRelay, create an API key scoped to that mailbox, and install the skill your deployment serves at /skills/SKILL.md in Codex with MARKRELAY_API_URL and MARKRELAY_API_KEY set. Codex loads it from ~/.agents/skills/markrelay-mail; mention it with $markrelay-mail, pick it from /skills, or let Codex choose it.
Can Codex read my other mailboxes?
No. A key reaches only what its owner can open, narrowed to the scope chosen for it. A key scoped to agent@ sees no other mailbox, in any call.
Is there an MCP server?
Yes. Every deployment is a remote MCP server at /mcp: add the URL, sign in, and pick the mailboxes it may use. Agents that run commands can use the skill and plain HTTP API instead, so nothing extra runs next to the agent.
Where does Codex keep the API key?
In your shell environment, for example as export lines in ~/.zshrc. Codex passes your shell's variables to the commands it runs. Never put the key in a repository.
What does it cost?
One MarkRelay license (Annual $99/year or Lifetime $249 once) covers any number of agent mailboxes. Cloudflare bills its own usage: Workers Paid ($5/month) includes 3,000 sent emails a month, then $0.35 per 1,000; receiving through Email Routing is free.
Go deeper
Explore more of MarkRelay
Use cases
Own your email stack today
Buy MarkRelay once and run it in your Cloudflare account. MarkRelay adds no per-message or per-seat charge; Cloudflare usage and service limits remain separate.