# Send leads to Mailchimp

> Add new leads to an audience, with their answers as merge fields.

Source: https://welcomeai.dev/docs/mailchimp
Category: Destinations
Updated: 2026-09-11

---
## What you need

An **API key**: Mailchimp → your avatar → Account & billing → Extras → API keys. The key ends with
its datacenter, for example `-us21`, which is how we know which server to talk to.

## Connect and route

1. In **Destinations**, connect Mailchimp with the key.
2. Create a route and pick the audience.
3. Map the fields. The email address is required. Your audience's merge fields (`FNAME`, `LNAME` and
   any you have added) appear in the list, and **New field** creates one if it is missing.

You can map a fixed value to the tags field to label everything that comes from the assistant.

## One route per widget, and so one per form

A route's scope is a widget. Leave it on all widgets and the route takes every lead; pin it to one
and it takes only that widget's.

That is also how two forms reach two places, because a widget runs one form: its lead capture names
the form it asks, so choosing the widget chooses the form. A contact form on one widget and a demo
request on another are two routes, each to its own destination. Two forms on the same widget is not a
thing you can set up -- swap the widget's form and you have changed which form it asks.

Choosing a widget does one more thing: the mapper's left column shows the questions **that** form
asks, instead of every question every form in the workspace asks. So a route built for the demo
request is not mapped against the contact form's fields, and the questions on screen are the ones a
visitor will actually be asked. Leave the route on all widgets and you get all of them, which is
right -- the route takes leads from all of them.

One consequence worth knowing: a lead captured by the assistant in conversation carries the widget it
came from, so a widget-scoped route takes it like any other. A lead pushed through the API with no
widget is taken only by a route with no widget.

## Subscription status

A new contact is added as subscribed. Someone who previously unsubscribed is **not** flipped back:
Mailchimp keeps their status and we never override it. That is deliberate, and it is what keeps you
compliant.

## Check it before a visitor does

- **Check connection** on the account re-asks Mailchimp whether the key still works and records the
  answer with today's date.
- **Send sample lead** adds one invented contact to the audience this route points at, so you can see
  exactly what arrives. It uses the same mapping a real lead uses, and the dispatch log marks it as a
  sample -- it is not stored as a lead and does not count against your plan. Remove the sample contact
  from the audience afterwards if you keep your list clean.

## When it fails

The dispatch log shows Mailchimp's own message. The three you will actually meet:

**"ada@example.com looks fake or invalid, please enter a real email address."** Mailchimp screens every
address before it accepts it, and refuses whole domains it treats as placeholders -- `example.com`
among them. The lead is still saved in WelcomeAI; only the Mailchimp send failed. There is nothing to
fix at this end: a visitor who typed a throwaway address will not reach an audience.

**"A Merge Field with the tag BUDGETRANG already exists for this list."** Mailchimp tags are ten
characters, and we build one from the field's label -- so two labels that start the same way used to
collide. We now step around a tag the audience already has (`BUDGETRAN2`), so you should not see this
unless you created the field in Mailchimp yourself. Field labels keep their accents: *Dirección de
envío* becomes `DIRECCIOND`.

**A merge field that does not exist on that audience.** The route maps onto a tag the audience no
longer has. Re-open the route, refresh the field list and map it again, or let the route builder create
the field for you.