---
title: "Validate and encrypt a Banger-managed source connection."
method: POST
path: "/v1/workspaces/{workspaceId}/connections/adapters/{adapterKey}"
---

# Validate and encrypt a Banger-managed source connection.

`POST /v1/workspaces/{workspaceId}/connections/adapters/{adapterKey}`

## Request

- Base URL: `https://api.bangermail.com`
- URL: `https://api.bangermail.com/v1/workspaces/{workspaceId}/connections/adapters/{adapterKey}`
- Auth: HTTP bearer

Connecting Mailchimp starts the move from Mailchimp at once (as startMailchimpMigration does), and the
response carries its first report in `mailchimp_migration`. Without display_name, a Mailchimp connection
is named after the account, e.g. "Mailchimp (Acme Inc)". Connecting a Mailchimp account that is already
connected answers 409 `mailchimp_account_already_connected` with `error.details.connection_id`.

## Headers

- `Idempotency-Key` string, required

## Request body

- ConnectionCredential
  - `api_key` string, required: API key or provider service-account JSON.
  - `display_name` string
  - `config` object

## Response `200`

Idempotent replay of an existing connection request.

- object
  - `data` Connection, required
    - `id` string, uuid, required
    - `adapter_key` string, required
    - `category` 'email' | 'customer' | 'product' | 'work' | 'data', required
    - `display_name` string, required
    - `status` 'pending_validation' | 'active' | 'error' | 'disabled', required
    - `auth_kind` 'api_key' | 'oauth2' | 'service_account' | 'none', required
    - `freshness_mode` 'webhook' | 'poll' | 'on_demand' | 'hybrid', required
    - `capabilities` string[], required
    - `resource_scope` object, required
    - `config` object, required: Non-secret adapter configuration such as a cloud host and project ID.
    - `active_credential_version` integer, nullable
    - `external_account_id` string, nullable
    - `external_account_name` string, nullable
    - `last_validated_at` string, date-time, nullable
    - `last_success_at` string, date-time, nullable
    - `last_error_code` string, nullable
    - `disabled_at` string, date-time, nullable
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `mailchimp_migration` MailchimpMigrationReport: The move from one Mailchimp connection into a product. Poll GET /mailchimp-migration for live progress: `phase` says where it is; `counts`, `audiences`, `segments`, `templates` and `campaigns` grow as it goes.
    - `migration_id` string, uuid, required
    - `connection_id` string, uuid, required
    - `product_id` string, uuid, required
    - `status` 'importing' | 'completed', required
    - `phase` 'importing' | 'copying_designs' | 'finishing' | 'completed' | 'needs_new_key' | 'disconnected', required: importing (reading Mailchimp), copying_designs (templates and campaigns), finishing, completed, needs_new_key (Mailchimp rejected the API key; the move is paused until a new key is saved with rotateConnectionCredential), or disconnected (the connection was removed; everything already moved stays in Banger and the counts stay readable).
    - `started_at` string, date-time, required
    - `completed_at` string, date-time, nullable, required
    - `connection` object, required
      - `display_name` string, required
      - `account_name` string, nullable, required
      - `status` 'pending_validation' | 'active' | 'error' | 'disabled', required
      - `last_error_code` string, nullable, required
      - `needs_new_key` boolean, required
      - `message` string: Present when needs_new_key or disconnected, ready to show.
    - `progress` object, required
      - `import_streams` integer, required
      - `import_streams_done` integer, required
      - `failing_streams` object[], required
        - `stream` string, required
        - `ref` string, required
        - `error_code` string, nullable, required
      - `designs_waiting` integer, required
      - `note` string, required
    - `counts` object, required
      - `contacts` integer, required
      - `subscribed` integer, required
      - `unsubscribed` integer, required
      - `bounced` integer, required
      - `contact_lists` integer, required
      - `contact_fields` integer, required
      - `segments_converted` integer, required
      - `segments_kept_as_lists` integer, required
      - `templates_imported` integer, required
      - `templates_to_rebuild` integer, required
      - `campaigns_imported_as_designs` integer, required
      - `automations_imported` integer, required
    - `audiences` object[], required
      - `mailchimp_id` string, required
      - `name` string, required
      - `list_id` string, uuid, nullable, required
      - `list_name` string, nullable, required
      - `members_in_banger` integer, required
      - `subscribed` integer, required
      - `unsubscribed` integer, required
      - `bounced` integer, required
      - `members_in_mailchimp` integer, required
    - `contact_fields` object[], required
      - `mailchimp_tag` string, required
      - `name` string, required
      - `field_key` string, required
      - `type` 'text' | 'number' | 'boolean' | 'date' | 'choice' | 'choices', required
    - `consent` string, required
    - `segments` MailchimpMigrationOutcome[], required
      - `mailchimp_id` string, required: Segments: <audience id>:<segment id>. Templates and campaigns: their Mailchimp id.
      - `became` 'segment' | 'contact_list' | 'template' | 'needs_rebuild', required
      - `id` string, uuid: The Banger segment
      - `name` string, required
      - `reason` string: Why a segment stayed a static list
      - `dropped_merge_tags` string[]: Mailchimp merge tags with no Banger equivalent, removed from the design (conditions on merge fields keep their first branch and are listed here).
      - `replaced_footer` boolean: Mailchimp's footer section (view in browser, preferences, address, badge) became the product's brand footer.
      - `removed_links` string[]: Links to Mailchimp-only pages outside the footer (such as view in browser) that were removed, by their words.
      - `links_to_fill` object[]: Links left empty in Mailchimp; each is now a URL slot of the design to fill before it can be sent.
        - `key` string, required
        - `label` string, required
      - `kept_edits` boolean: A re-run found the design edited in Banger and left it as it is.
    - `templates` MailchimpMigrationOutcome[], required
      - `mailchimp_id` string, required: Segments: <audience id>:<segment id>. Templates and campaigns: their Mailchimp id.
      - `became` 'segment' | 'contact_list' | 'template' | 'needs_rebuild', required
      - `id` string, uuid: The Banger segment
      - `name` string, required
      - `reason` string: Why a segment stayed a static list
      - `dropped_merge_tags` string[]: Mailchimp merge tags with no Banger equivalent, removed from the design (conditions on merge fields keep their first branch and are listed here).
      - `replaced_footer` boolean: Mailchimp's footer section (view in browser, preferences, address, badge) became the product's brand footer.
      - `removed_links` string[]: Links to Mailchimp-only pages outside the footer (such as view in browser) that were removed, by their words.
      - `links_to_fill` object[]: Links left empty in Mailchimp; each is now a URL slot of the design to fill before it can be sent.
        - `key` string, required
        - `label` string, required
      - `kept_edits` boolean: A re-run found the design edited in Banger and left it as it is.
    - `campaigns` MailchimpMigrationOutcome[], required
      - `mailchimp_id` string, required: Segments: <audience id>:<segment id>. Templates and campaigns: their Mailchimp id.
      - `became` 'segment' | 'contact_list' | 'template' | 'needs_rebuild', required
      - `id` string, uuid: The Banger segment
      - `name` string, required
      - `reason` string: Why a segment stayed a static list
      - `dropped_merge_tags` string[]: Mailchimp merge tags with no Banger equivalent, removed from the design (conditions on merge fields keep their first branch and are listed here).
      - `replaced_footer` boolean: Mailchimp's footer section (view in browser, preferences, address, badge) became the product's brand footer.
      - `removed_links` string[]: Links to Mailchimp-only pages outside the footer (such as view in browser) that were removed, by their words.
      - `links_to_fill` object[]: Links left empty in Mailchimp; each is now a URL slot of the design to fill before it can be sent.
        - `key` string, required
        - `label` string, required
      - `kept_edits` boolean: A re-run found the design edited in Banger and left it as it is.
    - `automations` object, required
      - `imported` false, required
      - `why` string, required
      - `next_steps` string[], required
      - `help_call_url` string, uri, required

## Other responses

- `201`: Credential validated, encrypted, and connected.
- `409`: An active connection with this name exists, or (`mailchimp_account_already_connected`, with `error.details.connection_id`) this Mailchimp account is already connected.

---

[API](https://skmtc.dev/bangermail/apis/banger-api.md) · [All operations](https://skmtc.dev/bangermail/apis/banger-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bangermail/apis/banger-api/revisions/a149909267f9?raw)