Maildeck API and MCP
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.
Addresses
Section titled “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
Section titled “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
Section titled “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.
- In Claude, open Settings → Connectors and choose Add custom connector.
- Name it
Maildeckand paste the addresshttps://api.maildeck.co/mcp. - Choose Connect. Claude opens Maildeck: sign in and approve what it may do.
- In a new chat, ask: What is the status of my Maildeck account?
-
In a terminal, run:
Terminal window claude mcp add --transport http maildeck https://api.maildeck.co/mcp -
Start Claude Code, run
/mcp, pick maildeck and choose Authenticate. Your browser opens Maildeck: sign in and approve. -
Ask: What is the status of my Maildeck account?
- In ChatGPT settings, open Connectors and create a custom connector. Depending on your plan, custom connectors may need developer mode turned on first.
- Use the address
https://api.maildeck.co/mcpand choose OAuth sign-in. - Sign in to Maildeck when asked and approve what it may do.
- In a chat with the connector on, ask: What is the status of my Maildeck account?
-
In the Maildeck app, open Settings → API & MCP, create a key and pick what it may do. Copy it: it is shown once.
-
Add Maildeck to your client’s
mcp.json:{"mcpServers": {"maildeck": {"url": "https://api.maildeck.co/mcp","headers": { "Authorization": "Bearer md_live_…" }}}} -
Restart the client and ask: What is the status of my Maildeck account?
Getting a key
Section titled “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_connectwith no key, show the person the link it returns, and callpoll_connectuntil 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
Section titled “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 |
- Nothing is charged through the API.
create_checkoutreturns a payment link for a person to pay. Pass thedue_now_centsfromquote_orderasexpected_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: trueis required oncreate_checkout,complete_order_setup,enable_maskinganddisable_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
Section titled “Errors”Errors come back as {"error": {"code": "...", "message": "..."}} with a matching HTTP status. The message is written to be shown to a person.