Connect an agent

This page is written so you can hand it to a coding agent. In Emailx, open API, MCP & CLI in the profile menu and copy the setup prompt, or paste this page’s address into your agent yourself.

Agents following these steps: ask the person for an API key; never invent one, print it back or store it in a repository. Before any step that launches a campaign, sends a message, uses AI credits or starts a purchase, ask the person to confirm.

1. Get an API key

The person creates the key in Emailx under API, MCP & CLI → New API key, choosing the workspaces, the access (None, Read or Full per area) and an expiry. Emailx shows the key once. Save it in a private file only the user can read:

mkdir -p ~/.config/emailx
# Paste the key as the only content of this file, then:
chmod 600 ~/.config/emailx/api-key

CLI

Needs Python 3.11 or newer.

python3 -m venv ~/.emailx-agent
~/.emailx-agent/bin/python -m pip install "emailx-agent[mcp] @ https://app.emailx.ai/api/emailx-agent.zip"
export EMAILX_BASE_URL="https://app.emailx.ai"
export EMAILX_API_KEY_FILE="$HOME/.config/emailx/api-key"
~/.emailx-agent/bin/emailx doctor --json

doctor should report the account and environment of the key. Then explore with emailx --help and emailx <group> --help; every command lists the fields it accepts. Add the two export lines to the shell profile so later sessions keep working.

MCP

Install the package as in the CLI section (it includes the MCP server), then add Emailx to your agent. Use absolute paths.

Claude Code
Cursor
Claude Desktop
Codex
Gemini CLI

claude mcp add emailx \
  -e EMAILX_BASE_URL=https://app.emailx.ai \
  -e EMAILX_API_KEY_FILE=$HOME/.config/emailx/api-key \
  -- $HOME/.emailx-agent/bin/emailx mcp serve --transport stdio

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "emailx": {
      "command": "/Users/you/.emailx-agent/bin/emailx",
      "args": ["mcp", "serve", "--transport", "stdio"],
      "env": {
        "EMAILX_BASE_URL": "https://app.emailx.ai",
        "EMAILX_API_KEY_FILE": "/Users/you/.config/emailx/api-key"
      }
    }
  }
}

Add the same emailx entry as for Cursor to claude_desktop_config.json (Settings → Developer → Edit config), then restart Claude Desktop.

Add to ~/.codex/config.toml:

[mcp_servers.emailx]
command = "/Users/you/.emailx-agent/bin/emailx"
args = ["mcp", "serve", "--transport", "stdio"]
env = { EMAILX_BASE_URL = "https://app.emailx.ai", EMAILX_API_KEY_FILE = "/Users/you/.config/emailx/api-key" }

Add the same emailx entry as for Cursor under mcpServers in ~/.gemini/settings.json.

Connect by URL (ChatGPT, Claude on the web, Grok)

Assistants that add MCP servers by URL use https://app.emailx.ai/mcp. You sign in to Emailx in the browser and choose the workspaces and access there; no key file is needed. This connection is available when it is enabled for your account.

Check it works

Ask the agent: “Which Emailx account and workspaces am I connected to?” It should call get_connection and list_workspaces and answer with your workspace names. Next: find the right endpoint, the MCP tools and the CLI commands.

Get started

Sending well

Build a workflow

Connect an agent

1. Get an API key

CLI

MCP

Connect by URL (ChatGPT, Claude on the web, Grok)

Check it works

​1. Get an API key

​CLI

​MCP

​Connect by URL (ChatGPT, Claude on the web, Grok)

​Check it works

1. Get an API key

CLI

MCP

Connect by URL (ChatGPT, Claude on the web, Grok)

Check it works