Connect an email platform (ESP)
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.
1. See what's connected
List every integration (connected and available):
curl https://api.mailfloss.com/v1/integrations \
-H "Authorization: Bearer YOUR_API_KEY"Or drill into one platform and all of its connections:
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:
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:
# 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
{
"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.
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
# 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.