---
title: "Start, or run again, the move from Mailchimp into this product."
method: POST
path: "/v1/workspaces/{workspaceId}/mailchimp-migration"
---

# Start, or run again, the move from Mailchimp into this product.

`POST /v1/workspaces/{workspaceId}/mailchimp-migration`

## Request

- Base URL: `https://api.bangermail.com`
- URL: `https://api.bangermail.com/v1/workspaces/{workspaceId}/mailchimp-migration`
- Auth: HTTP bearer

Connecting Mailchimp already starts it; running again re-syncs and adds only what is new. Needs contacts:write and campaigns:write; a signed-in person must be an owner or admin. No connection grant is needed.

## Request body

- object
  - `connection_id` string, uuid
  - `recent_campaigns` integer

## Response `202`

The move is running in the background.

- object
  - `data` object, required: 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
    - `message` string

## Other responses

- `409`: `mailchimp_connection_ambiguous`: several Mailchimp connections; pass connection_id.

---

[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)