MCP-postale.io

MCP server for the postale.io email hosting API.

Manage your postale.io account from any MCP-compatible AI agent — Claude Code, Claude Desktop, OpenAI Codex, Cursor, Windsurf and more. Full coverage of the official API: domains, DNS/DKIM records, white-label branding, mailboxes, Sieve filters, quotas, aliases, and email/authentication logs.

Documentación en español: README.es.md · AI agent install guide: llms-install.md · Full tool reference: docs/TOOLS.md

Features

• 31 tools covering all 39 endpoints of the postale.io API v1
• Domains — list, create (MX or TXT verification), update limits/catch-all/forwarding, delete
• DNS — suggested MX, SPF, DKIM, DMARC, verification TXT, autoconfig/autodiscover records, with the currently-found values so you can verify your DNS setup
• DKIM — inspect, generate, install (bring your own keys) and remove key pairs
• Branding — white-label webmail/admin: logos, favicon, support URL, colors, custom CSS
• Mailboxes — full CRUD, Sieve filter scripts, storage quotas, admin roles
• Aliases — full CRUD with multiple redirect targets
• Logs — daily email logs with raw SMTP/LMTP transcripts, and authentication logs for security auditing
• Safety — destructive operations (deleting domains, mailboxes, aliases, DKIM keys) require an explicit confirm: true argument, so an agent can never delete data by accident

Requirements

• Node.js ≥ 18
• A postale.io account on a plan with API access
• Your API key: postale.io admin panel → Account → API

Installation

Quick install (no clone needed)

The package can run straight from GitHub via npx — it builds itself on first install:

claude mcp add postale \
  --env POSTALE_API_KEY=your_api_key_here \
  -- npx -y github:fmendezy/MCP-postale.io

For other clients, use npx as the command with args ["-y", "github:fmendezy/MCP-postale.io"] in the JSON/TOML examples below.

From source

Get the code and build it:

git clone https://github.com/fmendezy/MCP-postale.io.git
cd MCP-postale.io
npm install   # also builds via the prepare script

The server binary is dist/index.js. All clients below use the same two things: the command node /absolute/path/to/MCP-postale.io/dist/index.js and the environment variable POSTALE_API_KEY.

Claude Code

claude mcp add postale \
  --env POSTALE_API_KEY=your_api_key_here \
  -- node /absolute/path/to/MCP-postale.io/dist/index.js

Then run /mcp inside Claude Code to verify the connection. Add --scope user to make it available in every project.

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "postale": {
      "command": "node",
      "args": ["/absolute/path/to/MCP-postale.io/dist/index.js"],
      "env": { "POSTALE_API_KEY": "your_api_key_here" }
    }
  }
}

OpenAI Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.postale]
command = "node"
args = ["/absolute/path/to/MCP-postale.io/dist/index.js"]

[mcp_servers.postale.env]
POSTALE_API_KEY = "your_api_key_here"

Cursor / Windsurf / other MCP clients

Any client that supports stdio MCP servers works with the same JSON shape as Claude Desktop above (Cursor: .cursor/mcp.json; Windsurf: ~/.codeium/windsurf/mcp_config.json).

Configuration

| Environment variable | Required | Default | Description | | --- | --- | --- | --- | | POSTALE_API_KEY | yes | — | Your postale.io API key (used as the HTTP Basic username, per the official API) | | POSTALE_BASE_URL | no | https://postale.io | API base URL override | | POSTALE_TIMEOUT | no | 30000 | Request timeout in milliseconds |

Available tools

| Group | Tools | | --- | --- | | Domains | list_domains, get_domain, create_domain, update_domain, delete_domain | | DNS & DKIM | get_domain_dns_record (mx/spf/dkim/dmarc/verification/autoconfig/autodiscover), get_domain_dkim, generate_domain_dkim, set_domain_dkim, delete_domain_dkim | | Branding | get_domain_brand, update_domain_brand | | Stats | get_domain_stats, get_mailbox_stats (emails in/out, last 30 days) | | Mailboxes | list_mailboxes, get_mailbox, create_mailbox, update_mailbox, delete_mailbox, get_mailbox_sieve, update_mailbox_sieve, get_mailbox_quota, update_mailbox_quota | | Aliases | list_aliases, get_alias, create_alias, update_alias, delete_alias | | Logs | list_email_logs, get_email_log_protocol, list_auth_logs |

See docs/TOOLS.md for every parameter and example prompts.

List endpoints are paginated (max 25 items per page) and accept an optional search query — the same rules as the underlying API.

Example prompts

Once connected, ask your agent things like:

• "List all my postale.io domains and tell me which ones have no DKIM keys."
• "Create the mailbox [email protected] with a strong random password."
• "Check whether the SPF and DMARC records of example.com match what postale.io suggests."
• "Show me yesterday's failed delivery attempts for example.com and the SMTP transcript of the first one."
• "Add a Sieve rule to [email protected] that files messages from @cliente.com into the folder Clientes." (the agent should fetch the current script first, then submit the merged script)
• "Who logged into IMAP on 2026-08-01 from an IP outside Chile?"

Security notes

• The API key grants full control over the account: treat it like a root password. Prefer per-client config files with restrictive permissions over shell profiles.
• Destructive tools require confirm: true; agents will ask you before deleting anything if you instruct them to confirm destructive actions (recommended).
• The server talks only to https://postale.io (or your POSTALE_BASE_URL) and never stores or logs your key.

Development

npm install
npm run build   # compile TypeScript to dist/
npm test        # smoke test: MCP handshake, tool list, validation, error handling
npm run dev     # tsc --watch

The project is intentionally small: src/client.ts (HTTP client with Basic auth and error mapping), src/tools.ts (tool definitions with zod schemas), src/index.ts (stdio entry point).

Issues and PRs are welcome.

License

MIT