Quickstart

Get your AI agent its own email address in two commands.

Prerequisites

Node.js 20+
OpenMail account (free, no credit card)

Claude Code
OpenClaw
API / SDK

Install the skill

Inside Claude Code, run:

/plugin marketplace add openmailsh/skills
/plugin install openmail@openmailsh-skills

Claude Code now knows how to use OpenMail.

Run setup

In your terminal:

npx @openmail/cli setup --agent claude-code

This opens your browser to sign in, prompts for a mailbox name, creates your inbox, and writes credentials to ~/.claude/openmail.env.

Verify

npx @openmail/cli status

Your agent can now send and receive email. Ask Claude Code to send a test email to confirm.

OpenClaw integration

Paths, WebSocket bridge, and links to the packaged skill files.

Skill files (SKILL.md)

SKILL.md matches @openmail/cli; reference pages come from openmailsh/skills.

Use this pre-built prompt to get started faster.

Open in Cursor

Install

npm install -g @openmail/cli

Setup

openmail setup

Creates your inbox, writes the skill file to ~/.openclaw/skills/openmail/SKILL.md, and saves credentials to ~/.openclaw/openmail.env. Pass --api-key om_... to skip the auth prompt.When setup completes, confirm everything is working:

openmail status

WebSocket bridge — Setup starts the bridge automatically via systemd (Linux) or launchd (macOS). On Windows, setup prints the command to run manually.

Send an email

openmail send --to hello@example.com --subject "Hello from OpenMail" --body "I have my own inbox!"

Add files with --attach (repeatable):

openmail send --to hello@example.com --subject "Report" --body "See attached" --attach report.pdf

Narrow the agent’s key

Setup signs you in with your account-wide key and stores it for the agent to use. That key reaches every inbox on your account. Once setup has created the agent’s inbox, swap it for an inbox-scoped key — the agent keeps working, but a compromised agent can no longer reach anything but its own inbox.

curl -X POST https://api.openmail.sh/v1/inboxes/<inbox-id>/api-keys \
  -H "Authorization: Bearer <account-key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent"}'

Replace OPENMAIL_API_KEY in the agent’s env file with the returned token. It is shown once, at creation. Minting needs your account-wide key, so run this yourself rather than handing the account key to the agent.

Setup itself needs the account-wide key — creating an inbox is outside what an inbox-scoped key can do, and the inbox has to exist before a key can be scoped to it. Narrow the key after setup, not before.

More commands

openmail messages list --direction inbound
openmail threads list
openmail threads get --thread-id <thread-id>

Next steps

OpenClaw - See the OpenClaw integration guide and the Skill files tab for SKILL.md and reference files.
Handle inbound email - Route replies to your agent via WebSocket or webhooks.
Improve deliverability - Follow warm-up schedules to stay out of spam.
Explore the API - Full API reference for programmatic workflows.

WebSockets

Real-time event streaming. No public URL needed.

Email deliverability

Warm-up schedules and content best practices.

Threading

How threads work across inbound and outbound.

API integration

Create inboxes programmatically for multi-tenant apps.

Get started

Core concepts

WebSockets

Webhooks

Guides

Integrations

Best practices

Resources

Security & privacy

Prerequisites

OpenClaw integration

Skill files (SKILL.md)

Narrow the agent’s key

More commands

Next steps

WebSockets

Email deliverability

Threading

API integration

​Prerequisites

OpenClaw integration

Skill files (SKILL.md)

​Narrow the agent’s key

​More commands

​Next steps

WebSockets

Email deliverability

Threading

API integration

Prerequisites

Narrow the agent’s key

More commands

Next steps