---
title: Connect an email platform (ESP)
slug: esp-connect
docTags: 
createdAt: 2026-06-02T09:00:53.233Z
---

mailfloss can verify and clean the contacts in your email platform
automatically. The Integrations API connects, configures, and manages those
connections across **18 supported platforms** — Klaviyo, Mailchimp, Brevo,
ActiveCampaign, ConvertKit, MailerLite, GetResponse, and more — through one
uniform surface.

Every endpoint takes an ESP **`type`** slug (e.g. `klaviyo`, `mailchimp`,
`activecampaign`) and addresses a specific connection by its `id`. One account
can hold **multiple connections** of the same type.

:::BlockQuote
**Naming:** the slug for Brevo is `brevo` (not the old `sendinblue`).
:::

## 1. See what's connected

List every integration (connected and available):

```bash
curl https://api.mailfloss.com/v1/integrations \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Or drill into one platform and all of its connections:

```bash
curl https://api.mailfloss.com/v1/integrations/klaviyo \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## 2. Connect

`POST /v1/integrations/{type}/connections` with the platform's credentials.
mailfloss **validates them live** (it fetches your lists during the connect call),
so a `201` means the credentials actually work — not just that they were stored.

Credentials are **encrypted at rest and never returned** by any endpoint.

The credential fields depend on the platform. Single-key platforms (Klaviyo,
MailerLite, Brevo, GetResponse, …) take just an `api_key`:

```bash
curl -X POST https://api.mailfloss.com/v1/integrations/klaviyo/connections \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Klaviyo",
    "credentials": { "api_key": "pk_xxxxxxxx" }
  }'
```

Others need more than one field — ActiveCampaign needs your account URL plus a
key; ConvertKit needs a key plus a secret:

```bash
# ActiveCampaign
curl -X POST https://api.mailfloss.com/v1/integrations/activecampaign/connections \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": {
      "api_url": "https://youraccount.api-us1.com",
      "api_key": "your-activecampaign-key"
    }
  }'

# ConvertKit
curl -X POST https://api.mailfloss.com/v1/integrations/convertkit/connections \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "credentials": { "api_key": "...", "api_secret": "..." } }'
```

`name` is optional and defaults to the platform's display name. The API
reference lists the exact credential fields for every supported platform —
check it for the one you're connecting.

A successful connect returns `201` with the new connection (see its shape
below). Other outcomes:

| Status | Meaning                                    |
| ------ | ------------------------------------------ |
| `400`  | Missing or malformed credentials.          |
| `402`  | Out of verification credits.               |
| `422`  | That `type` isn't connectable via the API. |

`POST` accepts an optional `Idempotency-Key` header so a retried connect won't
create a duplicate.

## 3. The connection object

```json
{
  "id": "cnx_8f3a",
  "name": "Marketing Klaviyo",
  "status": "active",
  "auto_floss_enabled": true,
  "created_at": "2026-06-02T09:00:00Z",
  "last_synced_at": null,
  "settings": {
    "aggressiveness": "normal",
    "verify_first": true,
    "checks": { "disposable": true, "nonexistent": true }
  }
}
```

- **`id`** — use this to address the connection in every other call.
- **`status`** — `active` or `disconnected`.
- **`auto_floss_enabled`** — whether automatic cleaning is on for this
  connection.
- **`settings`** — how aggressively mailfloss cleans (below).

## 4. Configure cleaning

`PATCH /v1/integrations/{type}/connections/{id}` — a partial update; omitted
fields are left unchanged. Three things you can set:

- **`verify_first`** (boolean) — verify new contacts before their first send.
- **`aggressiveness`** — `normal` (recommended preset), `aggressive` (all checks
  on), or `custom` (per-check control).
- **`checks`** — a map of individual check gates. Editing any gate switches
  `aggressiveness` to `custom`.

`aggressiveness` and `checks` are **mutually exclusive** in a single request
(send one or the other), and at least one field is required.

```bash
curl -X PATCH https://api.mailfloss.com/v1/integrations/klaviyo/connections/cnx_8f3a \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "verify_first": true, "aggressiveness": "aggressive" }'
```

### Keyword rules

Each connection has whitelist/blacklist keyword rules under
`.../connections/{id}/whitelist` and `.../blacklist` (list, add, bulk-add,
delete). See the API reference for the rule shape.

## 5. Disconnect and reconnect

```bash
# Disconnect (stops automatic cleaning; keeps the connection record)
curl -X DELETE https://api.mailfloss.com/v1/integrations/klaviyo/connections/cnx_8f3a \
  -H "Authorization: Bearer YOUR_API_KEY"

# Reconnect a previously disconnected connection
curl -X POST https://api.mailfloss.com/v1/integrations/klaviyo/connections/cnx_8f3a/reconnect \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Next steps

- **Errors** — connect-specific codes and how to handle them.
- **API reference** — exact credential fields per platform, the full `checks`
  gate list, and keyword-rule shapes.