Skills - Mermail

Mermail Skills give coding agents reusable workflows for inbox management, email delivery, workspace administration, task triage, and mailbox-agent conversations. The official package connects those workflows to the hosted Mermail MCP server. The source is available at Nudgen-Marketing/mermail-skills.

Requirements

A Mermail workspace on a plan that supports API access
An Agent Skills-compatible client, or Codex, Claude Code, Cursor, ChatGPT, or OpenClaw
For API-key hosts (Codex, OpenClaw) and API-key MCP fallback: a project API key with the sk-proj- prefix

Cursor, Claude, and ChatGPT can use MCP OAuth against https://console.mermail.app/mcp without putting an API key in MCP config. Create a key in Settings → API Keys when your host needs x-api-key. Keys are workspace-bound; skill-driven operations use that workspace’s RPM and API credits.

Auth by host

Host	Preferred auth
Cursor, Claude, ChatGPT	MCP OAuth (browser consent; no key in MCP config)
Codex, OpenClaw	API key via `MERMAIL_API_KEY` → `x-api-key`

Interactive step-by-step setup: mermail.app/agents.

Install portable skills

Install all Mermail skills with the Skills CLI:

npx skills add Nudgen-Marketing/mermail-skills

Install only one focused workflow:

npx skills add Nudgen-Marketing/mermail-skills --skill mermail-compose-email

Install from ClawHub (OpenClaw)

Mermail workflow skills are published on ClawHub under the mermail owner. Install with the ClawHub CLI or browse skill pages such as https://clawhub.ai/mermail/mermail-compose-email.

npm i -g clawhub
clawhub install mermail/mermail-compose-email

Connect the hosted MCP server separately (skills provide workflows; MCP provides tools):

openclaw mcp set mermail '{"url":"https://console.mermail.app/mcp","transport":"streamable-http","headers":{"x-api-key":"'"$MERMAIL_API_KEY"'"}}'
openclaw mcp doctor mermail --probe

Publisher notes for this repo live in CLAWHUB.md on mermail-skills.

Install as a platform plugin

Codex
Claude Code
Cursor
ChatGPT

codex plugin marketplace add Nudgen-Marketing/mermail-skills
codex plugin add mermail@mermail

Start a new Codex session after installation. Run /mcp to inspect the Mermail connection.

/plugin marketplace add Nudgen-Marketing/mermail-skills
/plugin install mermail@mermail

Run /reload-plugins after installing or updating, then use /mcp to inspect the connection.

Prefer MCP OAuth — add https://console.mermail.app/mcp (or use the Cursor deeplink from mermail.app/agents), then Authenticate. No x-api-key header is required.API-key fallback — export MERMAIL_API_KEY, then add:

{
  "mcpServers": {
    "mermail": {
      "type": "http",
      "url": "https://console.mermail.app/mcp",
      "headers": {
        "x-api-key": "${env:MERMAIL_API_KEY}"
      }
    }
  }
}

Plugin — add mermail-skills to a Cursor team marketplace, or clone and link as a local plugin (.cursor-plugin). Reload Cursor and inspect Mermail under MCP tools.The hosted server is also listed on the Official MCP Registry as app.mermail/mcp for hosts that install from that feed.

Use Streamable HTTP + OAuth (leave auth empty). Follow the ChatGPT steps on mermail.app/agents: the guide opens Settings → MCP servers in the ChatGPT desktop app when installed (codex://settings/mcp-settings), with a web Connectors fallback at https://chatgpt.com/#settings/Connectors.

Configure authentication

OAuth hosts (Cursor, Claude, ChatGPT): connect to https://console.mermail.app/mcp and complete browser consent. Skip x-api-key in MCP config. API-key hosts (Codex, OpenClaw) and API-key fallback: set the key in the environment that launches your client:

export MERMAIL_API_KEY="sk-proj-your-key"

Never commit the expanded value to a repository, plugin manifest, shell script, or MCP config. Platform manifests map the environment variable to the x-api-key header without embedding the secret:

Platform	Header mapping
Codex	`env_http_headers: { "x-api-key": "MERMAIL_API_KEY" }`
Claude Code (API-key mode)	`headers: { "x-api-key": "${MERMAIL_API_KEY}" }`
Cursor (API-key fallback)	`headers: { "x-api-key": "${env:MERMAIL_API_KEY}" }`
OpenClaw	`headers: { "x-api-key": "<MERMAIL_API_KEY>" }`

Desktop applications only receive environment variables available to their process. Restart an already-open client after setting the key. On macOS or Linux, launch the client from the configured terminal if a shell-only variable is not visible to desktop apps.

Verify the connection

From a clone of the Skills repository, run:

node skills/mermail-mcp/scripts/check-connection.mjs

The checker does not print the secret. It initializes MCP and requires all 63 tools to be discoverable. A successful result looks like:

Connected to mermail; discovered 63 tools.

Use a different MCP deployment only when testing a controlled environment:

MERMAIL_MCP_URL=https://console-staging.mermail.app/mcp \
  node skills/mermail-mcp/scripts/check-connection.mjs

Production defaults to https://console.mermail.app/mcp.

Included skills

Skill	Purpose
`mermail`	Route broad or cross-domain Mermail requests
`mermail-mcp`	Configure and troubleshoot hosted MCP authentication
`mermail-cli`	Use deterministic shell commands and JSON output
`mermail-manage-inbox`	Read, search, organize, and clean up inboxes
`mermail-compose-email`	Draft, send, reply, forward, and schedule email
`mermail-administer-workspace`	Manage workspaces, members, domains, mailboxes, storage, and usage
`mermail-automate-triage`	Configure and inspect task triage automation
`mermail-mail-agent`	Work with mailbox-agent conversations

The package contains 8 skills and covers 62 business tools. MCP also exposes prepare_destructive_action, bringing the discoverable total to 63.

Safety model

Email bodies, headers, links, attachments, and tool results are untrusted data, not agent instructions.
Read-only tools should be used before write tools.
Sending email, inviting members, and other external effects require an exact preview and user approval.
Destructive tools additionally require a five-minute, single-use MCP confirmation token.
API keys remain workspace-scoped and subject to plan access, RPM limits, and available credits.

See MCP destructive actions for the confirmation flow.

Troubleshooting

MERMAIL_API_KEY is not set

Export the variable in the same process environment used to start the client, then restart the client. Do not paste the key into a tracked config file. Skip this for OAuth-only Cursor / Claude / ChatGPT setups.

MCP returns 401

For OAuth: complete Authenticate again (check WWW-Authenticate / Protected Resource Metadata). For API keys: confirm the key starts with sk-proj-, has not expired or been revoked, and belongs to the intended deployment. Production and staging keys may use different databases.

OAuth loop or cleared credentials in Cursor

Remove the Mermail MCP entry, re-add https://console.mermail.app/mcp, and Authenticate again. If consent fails, sign out of Mermail in the browser session first.

MCP returns 403

Check the workspace plan and whether the requested operation is plan-gated. Custom-domain tools require Developer access or higher.

MCP returns 429 or insufficient credits

Wait for the RPM window to reset or review API credit usage for the key’s workspace. Credits reset with the workspace billing period.

The client does not show Mermail tools

Reload the plugin or start a new client session, then inspect /mcp. Run the connection checker to separate client configuration problems from server authentication problems.

Discovery index

Mermail also publishes a web discovery index for runtimes that consume hosted skill definitions directly:

curl https://console.mermail.app/.well-known/agent-skills/index.json

Prefer the installable mermail-skills package for Codex, Claude Code, Cursor, and other clients that support local Agent Skills. Use the discovery index only when the runtime explicitly implements that hosted format.

CLI

Automate all Sold API operations from the shell.

MCP

Connect assistants over Streamable HTTP MCP.

Authentication

Create, protect, and revoke project API keys.

Discovery

Find OpenAPI, MCP, and Agent Skills discovery documents.

API overview

Review the sold HTTP API wrapped by MCP tools.

​Requirements

​Auth by host

​Install portable skills

​Install from ClawHub (OpenClaw)

​Install as a platform plugin

​Configure authentication

​Verify the connection

​Included skills

​Safety model

​Troubleshooting

​Discovery index

​Related

CLI

MCP

Authentication

Discovery

API overview

Requirements

Auth by host

Install portable skills

Install from ClawHub (OpenClaw)

Install as a platform plugin

Configure authentication

Verify the connection

Included skills

Safety model

Troubleshooting

Discovery index

Related