> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Mailchimp as a data source
> Bring data from Mailchimp to Nekt.
## Overview
Mailchimp is an email marketing and automation platform used for audience management, email campaigns, and marketing analytics. This connector extracts audiences and their members, segments, email campaigns, campaign reports, and automation workflows from the Mailchimp Marketing API.
## Configuration
You can connect Mailchimp using either an **API key** or **OAuth**.
| Field | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **API Key** | Your Mailchimp API key. The data center is read automatically from its suffix (e.g. the `us9` in `abc123-us9`). Found under **Account → Extras → API keys**. |
| **Start Date** | *(Optional)* Start date for incremental data sync in ISO 8601 format (e.g., `2024-01-01T00:00:00Z`). Only applies to streams that support incremental replication. |
| **Data Center** | *(Optional)* Data center override (e.g. `us9`). Inferred from the API key suffix when omitted. |
To create an API key, go to **Account → Extras → API keys → Create A Key** in your Mailchimp account. Copy the key immediately — Mailchimp shows it only once.
Instead of an API key, you can click **Authorization** to connect via OAuth and grant access without copying a key. Use one method or the other.
Choose which streams you want to sync. Available streams are listed in the **Streams and Fields** section below.
For each selected stream, configure:
* **Layer**: Choose the destination layer (e.g., Bronze).
* **Folder**: Organize data within the layer.
* **Table name**: The table name in your lakehouse.
* **Sync Type**: Incremental (recommended) or Full Sync.
Set up the source-level configuration:
* **Description**: Add a description for this data source.
* **Triggers**: Configure sync triggers (schedule or manual).
* **Delta Log Retention Days**: Number of days to retain delta log history.
* **Full Sync**: Optionally force a full sync on first run.
After saving, verify the source appears in your **Sources** list. Run a manual sync to validate that data flows correctly.
## Streams and Fields
Audiences (lists) in the account, including contact details, signup settings, and aggregate stats. Synced as a full table.
| Field | Type | Description |
| ----------------------- | -------- | ---------------------------------------------------------------- |
| `id` | string | Unique audience identifier |
| `web_id` | integer | Numeric ID used in the Mailchimp web app |
| `name` | string | Audience name |
| `contact` | object | Contact information shown in campaign footers |
| `permission_reminder` | string | Permission reminder shown to subscribers |
| `use_archive_bar` | boolean | Whether the archive bar is enabled |
| `campaign_defaults` | object | Default from name, email, subject, and language |
| `notify_on_subscribe` | string | Email notified on new subscribes |
| `notify_on_unsubscribe` | string | Email notified on unsubscribes |
| `date_created` | datetime | When the audience was created |
| `list_rating` | integer | Star rating of the audience |
| `email_type_option` | boolean | Whether subscribers can choose an email type |
| `subscribe_url_short` | string | Shortened signup form URL |
| `subscribe_url_long` | string | Full signup form URL |
| `beamer_address` | string | Email-to-campaign (Mailchimp Beamer) address |
| `visibility` | string | Audience visibility (`pub` or `prv`) |
| `double_optin` | boolean | Whether double opt-in is enabled |
| `has_welcome` | boolean | Whether a welcome email is configured |
| `marketing_permissions` | boolean | Whether GDPR marketing permissions are enabled |
| `modules` | array | Enabled audience modules |
| `stats` | object | Aggregate stats (member counts, open/click rates, last activity) |
Members (contacts) of each audience. Child of `lists`. Supports incremental sync via `last_changed`.
| Field | Type | Description |
| ---------------------------------- | -------- | ------------------------------------------------------------------ |
| `id` | string | MD5 hash of the lowercased email — the member identifier |
| `email_address` | string | Member email address |
| `unique_email_id` | string | Unique email ID across the account |
| `contact_id` | string | Contact identifier |
| `full_name` | string | Member full name |
| `web_id` | integer | Numeric ID used in the Mailchimp web app |
| `email_type` | string | Preferred email type (`html` or `text`) |
| `status` | string | Subscription status (e.g. `subscribed`, `unsubscribed`, `cleaned`) |
| `unsubscribe_reason` | string | Reason for unsubscribing, if provided |
| `consents_to_one_to_one_messaging` | boolean | Whether the member consents to 1:1 messaging |
| `merge_fields` | string | Audience-specific merge fields (JSON; keys vary per audience) |
| `interests` | string | Interest group memberships (JSON; keys vary per audience) |
| `stats` | object | Member open/click rates and ecommerce data |
| `ip_signup` | string | IP address at signup |
| `timestamp_signup` | datetime | Signup timestamp |
| `ip_opt` | string | IP address at opt-in |
| `timestamp_opt` | datetime | Opt-in timestamp |
| `member_rating` | integer | Member engagement rating |
| `last_changed` | datetime | When the member record was last changed |
| `language` | string | Member language |
| `vip` | boolean | Whether the member is marked VIP |
| `email_client` | string | Last known email client |
| `location` | object | Geolocation (lat/long, country, timezone) |
| `marketing_permissions` | array | GDPR marketing permission states |
| `last_note` | object | Most recent note on the member |
| `source` | string | Signup source |
| `tags_count` | integer | Number of tags applied |
| `tags` | array | Tags applied to the member |
| `list_id` | string | Parent audience identifier |
Segments within each audience. Child of `lists`. Supports incremental sync via `updated_at`.
| Field | Type | Description |
| -------------- | -------- | -------------------------------------------------------------- |
| `id` | integer | Unique segment identifier (numeric) |
| `name` | string | Segment name |
| `member_count` | integer | Number of members in the segment |
| `type` | string | Segment type (e.g. `saved`, `static`, `fuzzy`) |
| `created_at` | datetime | When the segment was created |
| `updated_at` | datetime | When the segment was last updated |
| `options` | string | Match logic and conditions (JSON; structure varies by segment) |
| `list_id` | string | Parent audience identifier |
Email campaigns including recipients, settings, tracking, and a report summary. Supports incremental sync via `create_time`.
| Field | Type | Description |
| --------------------- | -------- | -------------------------------------------------------- |
| `id` | string | Unique campaign identifier |
| `web_id` | integer | Numeric ID used in the Mailchimp web app |
| `parent_campaign_id` | string | Parent campaign ID (for variations) |
| `type` | string | Campaign type (e.g. `regular`, `automation`, `rss`) |
| `create_time` | datetime | When the campaign was created |
| `archive_url` | string | Archive URL |
| `long_archive_url` | string | Full archive URL |
| `status` | string | Campaign status (e.g. `save`, `schedule`, `sent`) |
| `emails_sent` | integer | Number of emails sent |
| `send_time` | datetime | When the campaign was sent |
| `content_type` | string | Content type |
| `needs_block_refresh` | boolean | Whether content blocks need refreshing |
| `resendable` | boolean | Whether the campaign can be resent |
| `recipients` | object | Target audience and segment details |
| `settings` | object | Subject, from name, template, and footer settings |
| `tracking` | object | Open/click/ecommerce tracking settings |
| `report_summary` | object | Aggregate performance summary (opens, clicks, ecommerce) |
Per-campaign aggregate reports. The `id` matches the campaign id. Supports incremental sync via `send_time`.
| Field | Type | Description |
| ---------------- | -------- | --------------------------------------------------- |
| `id` | string | Report (campaign) identifier |
| `campaign_title` | string | Campaign title |
| `type` | string | Campaign type |
| `list_id` | string | Audience identifier |
| `list_is_active` | boolean | Whether the audience is active |
| `list_name` | string | Audience name |
| `subject_line` | string | Email subject line |
| `preview_text` | string | Email preview text |
| `emails_sent` | integer | Number of emails sent |
| `abuse_reports` | integer | Number of abuse reports |
| `unsubscribed` | integer | Number of unsubscribes |
| `send_time` | datetime | When the campaign was sent |
| `rss_last_send` | datetime | Last RSS send time |
| `bounces` | object | Hard/soft bounces and syntax errors |
| `forwards` | object | Forward counts and opens |
| `opens` | object | Open totals, unique opens, open rate, last open |
| `clicks` | object | Click totals, unique clicks, click rate, last click |
| `facebook_likes` | object | Facebook like counts |
| `list_stats` | object | Audience sub/unsub/open/click rates |
Classic automation workflows including recipients, settings, and a report summary. Supports incremental sync via `create_time`.
| Field | Type | Description |
| ------------------ | -------- | ---------------------------------------------------- |
| `id` | string | Unique automation (workflow) identifier |
| `create_time` | datetime | When the automation was created |
| `start_time` | datetime | When the automation started |
| `status` | string | Automation status (e.g. `save`, `sending`, `paused`) |
| `emails_sent` | integer | Number of emails sent |
| `recipients` | object | Target audience details |
| `settings` | object | Title, from name, and footer settings |
| `tracking` | object | Open/click/ecommerce tracking settings |
| `trigger_settings` | string | Workflow trigger configuration (JSON) |
| `report_summary` | object | Aggregate performance summary (opens, clicks) |
## Implementation Notes
* **Authentication**: HTTP Basic Auth with the API key (any username, API key as password), or OAuth via the **Authorization** button. The data center (e.g. `us9`) is resolved from the API key suffix or the OAuth metadata endpoint.
* **Pagination**: The connector paginates with `count` and `offset`, fetching all pages up to each endpoint's total.
* **Incremental sync**: `list_members`, `segments`, `campaigns`, `reports`, and `automations` sync incrementally using Mailchimp's `since_*` date filters. `lists` is full-table only, since Mailchimp exposes only a creation date for audiences.
* **JSON fields**: Fields with audience-specific or variable structure — `merge_fields`, `interests` (members), `options` (segments), and `trigger_settings` (automations) — are serialized as JSON strings. Parse them downstream as needed.
* **Child streams**: `list_members` and `segments` are synced per audience, using the parent `lists` stream to provide each `list_id`.