NOMA Sync Docs

Appearance

Mailchimp List & Tag Mapping

Why List and Tag Mapping? ​

Mailchimp uses lists (audiences) and tags to segment subscribers. In NOMA Sync: the Mailchimp webhook is audit-only (logs to sync_log; does not update LGL). Givebutter/Square → Mailchimp uses list mapping to decide which Mailchimp list(s) to add contacts to. LGL subscription status is updated by LGL's built-in Mailchimp integration (nightly).

Configuration is in Dashboard → Mailchimp Settings.

List Mapping ​

What it does: Associates a Mailchimp list (by list ID or name) with an internal “source” or LGL concept (e.g. newsletter list). When the Worker receives a Mailchimp webhook, it uses this mapping for audit context (which list the event refers to). For Givebutter/Square → Mailchimp, list mapping determines which list(s) to add contacts to. LGL is not updated from the webhook.

Typical setup:

  • Map Givebutter (and optionally Square) to your primary Mailchimp list so new donors/registrants are added. Webhook events are logged for audit only; LGL subscription status comes from LGL's Mailchimp integration.

Details depend on the Worker implementation (lib/mailchimp-list-mapper.ts, lib/mailchimp-tag-rules.ts). The dashboard UI may show list ID, optional LGL list/tag, and enable/disable sync per list.

Tag Rules ​

What they do: Define how Mailchimp tags (or list membership) are used for Givebutter/Square → Mailchimp (e.g. which tags to apply) or audit; the webhook does not update LGL.

Example: When adding a Givebutter donor to Mailchimp, apply tags such as Donor per tag rules. The webhook does not use tag rules to update LGL.

Tag rules are stored in D1. Configure them in Mailchimp Settings (add/edit/delete rules).

API Reference ​

  • GET /api/mailchimp/mappings – List current list/tag mappings (or equivalent).
  • POST /api/mailchimp/mappings – Create or update mapping (body format per dashboard/API).
  • GET /api/mailchimp/tag-rules – List tag rules.
  • POST /api/mailchimp/tag-rules – Create or update tag rules.

Access requires admin or super_admin role.

Source Types ​

The codebase may use “source types” (e.g. givebutter, square, mailchimp_list) for Givebutter/Square → Mailchimp list and tag behavior; webhook uses list mapping for audit only. List mapping and tag rules feed into that. See lib/mailchimp-list-mapper.ts and Mailchimp PRD in the noma-sync repo (0-docs/mailchimp/) for full behavior.