Connect an email platform (ESP)
mailfloss can verify and clean the contacts in your email platform automatically. The Integrations API lists, configures, and manages those connections through one uniform surface.
What you can do, by platform
Every platform mailfloss supports works with most of the Integrations API. Connecting, testing credentials and refreshing lists talk to the platform with your credentials, so they work only on the platforms below.
What | Platforms |
|---|---|
List integrations, get a connection, change cleaning settings, keyword rules, disconnect | Every supported platform |
Connect, test credentials, refresh lists | ActiveCampaign, ActiveTrail, beehiiv, Benchmark, Braze, Brevo, Campaigner, ClickFunnels, ConvertKit, Customer.io, DailyStory, Drip, Emma, GetResponse, Ghost, Gist, iContact, Iterable, Klaviyo, Mailchimp, MailerLite, Moosend, Ontraport, Ortto, Remarkety, Sendlane, SendPulse, Wishpond |
Connect any other platform from the mailfloss dashboard, then manage it here. Platforms that only sign in through their own login page, such as HubSpot, can't be connected with an API call.
Some details vary by platform:
- Settings. Not every platform supports every setting. For example, beehiiv and ClickFunnels have no Autofloss. A setting a platform doesn't support returns 422.
- Test and refresh need stored credentials the API can use. Most connections made in the dashboard by signing in to the platform return 409, even on a platform listed above. Klaviyo one-click connections are the exception: they test and refresh normally.
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 and blacklist keyword rules under .../connections/{id}/keywords/whitelist and .../keywords/blacklist (list and add, and delete one rule at .../keywords/{list}/{ruleId}). See the API reference for the rule shape.
5. Disconnect
# 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"To reconnect a disconnected connection, use Reconnect on the Integrations page in the dashboard.
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.