# MCP-postale.io

**MCP server for the [postale.io](https://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](https://postale.io/api/doc): domains, DNS/DKIM records, white-label branding, mailboxes, Sieve filters, quotas, aliases, and email/authentication logs.

> Documentación en español: [README.es.md](README.es.md) · AI agent install guide: [llms-install.md](llms-install.md) · Full tool reference: [docs/TOOLS.md](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 (recommended)

The package is published on npm as [`postale-mcp`](https://www.npmjs.com/package/postale-mcp) — no clone or build needed:

```bash
claude mcp add postale \
  --env POSTALE_API_KEY=your_api_key_here \
  -- npx -y postale-mcp
```

For other clients, use `npx` as the command with args `["-y", "postale-mcp"]` in the JSON/TOML examples below. (Running straight from GitHub also works: `npx -y github:fmendezy/MCP-postale.io`.)

### From source

Get the code and build it:

```bash
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

```bash
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):

```json
{
  "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`:

```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](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 soporte@example.com 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 ventas@example.com 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

```bash
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](LICENSE)