# API: Connections

> Connections operations of the Maildeck API: list_domain_replacements, request_domain_replacements, check_replacement_domains, withdraw_domain_replacement, connect_sequencer, connect_calendar, disconnect_calendar.

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

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

## list_domain_replacements

`GET /v1/domains/replacements` · scope: **read** · MCP tool: `list_domain_replacements`

This account's domain replacement requests and where each one stands.

status is requested (not started), in_progress (the team is on it), done, declined or cancelled.

```bash
curl -X GET "https://api.maildeck.co/v1/domains/replacements" \
  -H "Authorization: Bearer $MAILDECK_API_KEY"
```

## request_domain_replacements

`POST /v1/domains/replacements` · scope: **write** · MCP tool: `request_domain_replacements`

Ask Maildeck to replace burned domains. The team rebuilds the inboxes at no charge.

Show the person the exact old and new domains and get their agreement first: the old domain's inboxes are retired. For a blacklisted domain (kind "domain") give new_domain, a domain the person owns; each one must pass the same check as check_replacement_domains or the whole request is refused with per-line errors. For a blocked tenant (kind "tenant") give only old_domain: we supply the replacement. Follow progress with list_domain_replacements. Find out why domains were listed before replacing many: new ones can be listed for the same reason.

| Body field | Type | Required | Notes |
|---|---|---|---|
| `items` | array of object | yes | Up to 200 domains per request |
| `note` | string | no | Anything the team should know. up to 1000 chars |
| `idempotency_key` | string | yes | Any unique string for this action. Sending the same one again returns the first result instead of repeating the action. up to 200 chars |
| `confirm` | boolean | yes | Must be true. Confirms the person has agreed to this action |

```bash
curl -X POST "https://api.maildeck.co/v1/domains/replacements" \
  -H "Authorization: Bearer $MAILDECK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[],"idempotency_key":"a-unique-string","confirm":true}'
```

## check_replacement_domains

`POST /v1/domains/replacements/check` · scope: **write** · MCP tool: `check_replacement_domains`

Check whether new domains are fit to replace burned ones. Changes nothing.

Use this before request_domain_replacements: new domains are sometimes blacklisted out of the box. Only allow: true may be used; "could not check yet" is not a pass, so try again later. Up to 10 domains per call. The person buys the new domains at any registrar first.

| Body field | Type | Required | Notes |
|---|---|---|---|
| `domains` | array of string | yes | The new domains to check |

```bash
curl -X POST "https://api.maildeck.co/v1/domains/replacements/check" \
  -H "Authorization: Bearer $MAILDECK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domains":[]}'
```

## withdraw_domain_replacement

`POST /v1/domains/replacements/{request_id}/withdraw` · scope: **write** · MCP tool: `withdraw_domain_replacement`

Take back a replacement request the team has not started.

Refused once the team has started: the person then messages support.

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `request_id` | path | string | yes | request_id from list_domain_replacements |

| Body field | Type | Required | Notes |
|---|---|---|---|
| `idempotency_key` | string | yes | Any unique string for this action. Sending the same one again returns the first result instead of repeating the action. up to 200 chars |

```bash
curl -X POST "https://api.maildeck.co/v1/domains/replacements/<request_id>/withdraw" \
  -H "Authorization: Bearer $MAILDECK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idempotency_key":"a-unique-string"}'
```

## connect_sequencer

`POST /v1/sequencer` · scope: **write** · MCP tool: `connect_sequencer`

Save the sending tool's API key so Maildeck can read real sending numbers.

Supported for sending stats: instantly, smartlead, plusvibe, manyreach. The key is stored encrypted and never returned. Reading starts in the background; get_account_status shows whether the sequencer is connected.

| Body field | Type | Required | Notes |
|---|---|---|---|
| `provider` | string | yes | The sending tool, e.g. instantly, smartlead, plusvibe, manyreach. up to 40 chars |
| `api_key` | string | yes | An API key created in the sending tool. up to 2000 chars |
| `workspace` | string | no | Workspace name inside the tool, if it has several. up to 200 chars |
| `idempotency_key` | string | yes | Any unique string for this action. Sending the same one again returns the first result instead of repeating the action. up to 200 chars |

```bash
curl -X POST "https://api.maildeck.co/v1/sequencer" \
  -H "Authorization: Bearer $MAILDECK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"…","api_key":"…","idempotency_key":"a-unique-string"}'
```

## connect_calendar

`POST /v1/calendar` · scope: **write** · MCP tool: `connect_calendar`

Connect Calendly with a personal access token so booked calls are counted.

Create the token in Calendly → Integrations → API & Webhooks → Personal access tokens. It is checked at once, stored encrypted and never returned. Only Calendly is supported.

| Body field | Type | Required | Notes |
|---|---|---|---|
| `token` | string | yes | Calendly personal access token. up to 4000 chars |
| `idempotency_key` | string | yes | Any unique string for this action. Sending the same one again returns the first result instead of repeating the action. up to 200 chars |

```bash
curl -X POST "https://api.maildeck.co/v1/calendar" \
  -H "Authorization: Bearer $MAILDECK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token":"…","idempotency_key":"a-unique-string"}'
```

## disconnect_calendar

`DELETE /v1/calendar` · scope: **write** · MCP tool: `disconnect_calendar`

Disconnect the calendar. Booked calls stop being counted.

| Body field | Type | Required | Notes |
|---|---|---|---|
| `idempotency_key` | string | yes | Any unique string for this action. Sending the same one again returns the first result instead of repeating the action. up to 200 chars |

```bash
curl -X DELETE "https://api.maildeck.co/v1/calendar" \
  -H "Authorization: Bearer $MAILDECK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idempotency_key":"a-unique-string"}'
```
