Skip to content

API: Connect

← API overview

POST /v1/connect · scope: none · MCP tool: start_connect

Ask for access to a Maildeck account. Returns a link for the person to approve.

Use this when you have no API key. Show connect_url to the person: they sign in or create a Maildeck account, see which agent is asking and for what, and approve. Then call poll_connect with poll_token every few seconds; it returns the API key exactly once. The request expires after 15 minutes.

Body fieldTypeRequiredNotes
agent_namestringyesHow this agent is named to the person, e.g. “Acme growth agent”. up to 60 chars
scopesarray of read / billing / writenoread: see the account. billing: quote and create payment links. write: set up orders, masking and connections. default ["read"]
Terminal window
curl -X POST "https://api.maildeck.co/v1/connect" \
-H "Content-Type: application/json" \
-d '{"agent_name":"…"}'

POST /v1/connect/poll · scope: none · MCP tool: poll_connect

Check whether the person approved. Returns the API key once, on approval.

status: pending (keep polling every 5 seconds), approved (api_key is in this answer and will not be shown again: store it), denied, expired, or delivered (the key was already handed out).

Body fieldTypeRequiredNotes
poll_tokenstringyesup to 200 chars
Terminal window
curl -X POST "https://api.maildeck.co/v1/connect/poll" \
-H "Content-Type: application/json" \
-d '{"poll_token":"…"}'