API: Connect
start_connect
Section titled “start_connect”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 field | Type | Required | Notes |
|---|---|---|---|
agent_name | string | yes | How this agent is named to the person, e.g. “Acme growth agent”. up to 60 chars |
scopes | array of read / billing / write | no | read: see the account. billing: quote and create payment links. write: set up orders, masking and connections. default ["read"] |
curl -X POST "https://api.maildeck.co/v1/connect" \ -H "Content-Type: application/json" \ -d '{"agent_name":"…"}'poll_connect
Section titled “poll_connect”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 field | Type | Required | Notes |
|---|---|---|---|
poll_token | string | yes | up to 200 chars |
curl -X POST "https://api.maildeck.co/v1/connect/poll" \ -H "Content-Type: application/json" \ -d '{"poll_token":"…"}'