# API: Connect

> Connect operations of the Maildeck API: start_connect, poll_connect.

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

[← API overview](https://docs.maildeck.co/api/)

## 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"]` |

```bash
curl -X POST "https://api.maildeck.co/v1/connect" \
  -H "Content-Type: application/json" \
  -d '{"agent_name":"…"}'
```

## 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 |

```bash
curl -X POST "https://api.maildeck.co/v1/connect/poll" \
  -H "Content-Type: application/json" \
  -d '{"poll_token":"…"}'
```
