Connect a new connection (with credentials)

POST

/v1/integrations/{type}/connections

Creates a brand-new connection for the ESP type with fresh credentials. The credentials shape depends on type; the single-key ESPs currently connectable via the API (Klaviyo, MailerLite) take { "credentials": { "api_key": "..." }, "name"?: "..." }. The key is validated against the ESP live before anything is stored (a rejected key → 400 invalid_credentials, nothing written), then encrypted at rest; it is never returned. On success returns 201 with the new connection in the same shape as GET /v1/integrations/{type}/connections/{id}. A valid ESP slug that cannot be connected via the API yet (OAuth ESPs, or ESPs not wired) → 422 unsupported_integration (connect it in the dashboard); an unknown slug → 404. (org, type) is 1:N, so this always creates a new connection. Honors Idempotency-Key (a retried POST with the same key replays the original 201 instead of creating a duplicate).

Request

Authorization

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Path Params

Header Params

Body Params application/json

Examples

Responses

🟢201

application/json

Connection created

Bodyapplication/json

🟠400

🟠401

🟠403

🟠404

🟠409

🟠422

🟠429

🔴500

🔴503

Request Example

Shell

JavaScript

Java

Swift

curl --location 'https://api.mailfloss.com/v1/integrations//connections' \
--header 'Idempotency-Key;' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "name": "string",
    "credentials": {
        "api_key": "string"
    }
}'

Response Example

201 - Success

{
    "id": "conn_5d4c3b2a1e0f9z",
    "name": "Main Marketing List",
    "status": "active",
    "created_at": "2026-02-10T14:20:00Z",
    "last_synced_at": null,
    "settings": {
        "aggressiveness": "normal",
        "manual_mode": false,
        "autofloss": true,
        "decay_protection": true,
        "instafloss": false,
        "action": "unsubscribe",
        "checks": {
            "disposable": true,
            "nonexistent": true,
            "deactivated": true,
            "inbox_full": true,
            "bounced": true,
            "banned_words": true,
            "role_based": true,
            "complainers": true,
            "spam": true,
            "failed_exchange": true,
            "unverified": true,
            "accept_all": false
        },
        "blacklist_count": 5,
        "whitelist_count": 2
    }
}

Modified at 2026-10-20 13:54:45

Read one integration with all of its connections

Read one connection