# Maildeck API and MCP

> Buy, set up and monitor cold email infrastructure from your own code or an AI agent.

Source: https://docs.maildeck.co/api/

> **Caution: Early access**
> The API is switched on account by account while it is in early access. If it is on for you, the app says so at the top of **Settings → API & MCP**. If you want it, ask us in the app chat or at help@maildeck.co. Until it is on, keys are refused with `api_access_not_enabled`.

Buy, set up and monitor cold-email infrastructure. Every operation here is also an MCP tool of the same name at /mcp. Authenticate with "Authorization: Bearer md_live_…". The API never charges a card: buying returns a payment link for a person to pay. Writes take an idempotency_key; chargeable or irreversible actions also need confirm: true. Start with get_account_status.

<CopyForAI />

## Addresses

| | |
|---|---|
| REST | `https://api.maildeck.co/v1` |
| MCP (Streamable HTTP) | `https://api.maildeck.co/mcp` |
| OpenAPI | `https://api.maildeck.co/v1/openapi.json` |
| For agents | `https://api.maildeck.co/v1/llms.txt` |

## Agent discovery

An agent that only has `api.maildeck.co` can read everything it needs from the following well-known documents. No key is required.

| | |
|---|---|
| MCP server card (SEP-1649) | `https://api.maildeck.co/.well-known/mcp/server-card.json` |
| API catalog (RFC 9727) | `https://api.maildeck.co/.well-known/api-catalog` |
| OAuth protected resource (RFC 9728) | `https://api.maildeck.co/.well-known/oauth-protected-resource` |
| OAuth authorization server (RFC 8414) | `https://api.maildeck.co/.well-known/oauth-authorization-server` |
| OpenID Connect discovery | `https://api.maildeck.co/.well-known/openid-configuration` |
| Agent quickstart | `https://api.maildeck.co/auth.md` |

## Connect your AI agent

Most AI apps only need the MCP address. The app sends you to Maildeck to sign in, you choose what it may do, and no key is copied anywhere. It takes about two minutes.

**Claude (web and desktop)**

1. In Claude, open **Settings → Connectors** and choose **Add custom connector**.
2. Name it `Maildeck` and paste the address `https://api.maildeck.co/mcp`.
3. Choose **Connect**. Claude opens Maildeck: sign in and approve what it may do.
4. In a new chat, ask: *What is the status of my Maildeck account?*

**Claude Code**

1. In a terminal, run:

   ```bash
   claude mcp add --transport http maildeck https://api.maildeck.co/mcp
   ```

2. Start Claude Code, run `/mcp`, pick **maildeck** and choose **Authenticate**. Your browser opens Maildeck: sign in and approve.
3. Ask: *What is the status of my Maildeck account?*

**ChatGPT**

1. In ChatGPT settings, open **Connectors** and create a custom connector. Depending on your plan, custom connectors may need developer mode turned on first.
2. Use the address `https://api.maildeck.co/mcp` and choose OAuth sign-in.
3. Sign in to Maildeck when asked and approve what it may do.
4. In a chat with the connector on, ask: *What is the status of my Maildeck account?*

**Cursor and others (key)**

1. In the Maildeck app, open **Settings → API & MCP**, create a key and pick what it may do. Copy it: it is shown once.
2. Add Maildeck to your client's `mcp.json`:

   ```json
   {
     "mcpServers": {
       "maildeck": {
         "url": "https://api.maildeck.co/mcp",
         "headers": { "Authorization": "Bearer md_live_…" }
       }
     }
   }
   ```

3. Restart the client and ask: *What is the status of my Maildeck account?*

> **Tip**
> The first answer comes from `get_account_status`: what your account has and what to do next. If the agent says access is not enabled, your account is not on the early-access list yet.

## Getting a key

- **In the app:** Settings → API & MCP → create a key and pick its scopes. The key is shown once.
- **From an agent:** call `start_connect` with no key, show the person the link it returns, and call `poll_connect` until they approve. The key comes back once.
- **MCP apps** (Claude, ChatGPT, Cursor, Claude Code): add the MCP address as a connector. The app signs the person in to Maildeck and they approve what it may do.

Send the key on every call: `Authorization: Bearer md_live_…`.

## Scopes

| Scope | Lets the key |
|---|---|
| `read` | See the account, domains, orders, setup, masking and blacklist status; ask Maya |
| `billing` | Price orders and create payment links |
| `write` | Save order setup, finish setup, turn masking on or off, connect a sequencer or Calendly |

## Rules

- **Nothing is charged through the API.** `create_checkout` returns a payment link for a person to pay. Pass the `due_now_cents` from `quote_order` as `expected_due_now_cents`, so a price change fails instead of charging something unexpected.
- **Every write takes an `idempotency_key`.** Sending the same one again returns the first result.
- **`confirm: true`** is required on `create_checkout`, `complete_order_setup`, `enable_masking` and `disable_masking`.
- **Logins and API keys go in, never out.** Registrar, sequencer and DNS credentials can be saved; no call returns them.
- **Cancelling is done by a person in the app**, not through the API.
- **Start with `get_account_status`.** It lists what the account has and the next actions, most urgent first.

## Errors

Errors come back as `{"error": {"code": "...", "message": "..."}}` with a matching HTTP status. The message is written to be shown to a person.

## Reference

  - [Connect](https://docs.maildeck.co/api/connect/): start_connect, poll_connect
  - [Catalogue](https://docs.maildeck.co/api/catalogue/): get_pricing, check_domains
  - [Account](https://docs.maildeck.co/api/account/): get_account_status
  - [Domains](https://docs.maildeck.co/api/domains/): list_domains, get_domain_health
  - [Orders](https://docs.maildeck.co/api/orders/): list_orders, get_order
  - [Buying](https://docs.maildeck.co/api/buying/): quote_order, create_checkout, get_checkout
  - [Setup](https://docs.maildeck.co/api/setup/): get_order_setup, update_order_setup, complete_order_setup
  - [Connections](https://docs.maildeck.co/api/connections/): list_domain_replacements, request_domain_replacements, check_replacement_domains, withdraw_domain_replacement, connect_sequencer, connect_calendar, disconnect_calendar
  - [Masking](https://docs.maildeck.co/api/masking/): get_masking, enable_masking, disable_masking, get_masking_guide, add_masking_credential, verify_masking
  - [Maya](https://docs.maildeck.co/api/maya/): ask_maya
