Core Forms
Get Core Forms

Mailchimp API Integration

Subscribe to Mailchimp (API) adds or updates an audience contact using the Mailchimp Marketing API. It requires no companion WordPress plugin. The existing Mailchimp action remains available for sites using MC4WP, with its existing settings and filters unchanged.

Action type: mailchimp_api

Setup

  1. Open your form's Actions tab and choose Subscribe to Mailchimp (API) under Marketing & CRM.
  2. Paste your full Mailchimp API key, including the server suffix such as -us21. The field masks the key.
  3. Enter your Audience ID from Mailchimp audience settings.
  4. Choose your form's Email field. Optionally map first and last name.
  5. Keep Send double opt-in confirmation for new contacts, or choose immediate subscription when the person has agreed to receive your emails.
  6. Add any required custom audience merge fields as a JSON object, for example {"COMPANY":"[COMPANY]"}.
  7. Save the form. Use Test action with your own test address when ready; this makes a real request and can send a Mailchimp confirmation email.

Behavior

  • New contacts default to pending and receive Mailchimp's double opt-in confirmation.
  • The action uses the add-or-update endpoint with a stable hash of the lowercase email address. Repeating a request updates the same contact rather than creating a duplicate.
  • Only status_if_new is sent. Existing subscription status is preserved; the action does not force an unsubscribed contact back to subscribed.
  • First and last name map to FNAME and LNAME. Additional JSON fields use your audience's merge tags and can include form variables. Empty optional name mappings leave existing names alone.
  • HTTP failures and invalid responses are failures in Core Forms. Rate limits and transient provider failures are eligible for the shared retry queue. Provider response bodies and API keys are not included in error messages.
  • Spam and submissions still awaiting payment do not reach Mailchimp.

Troubleshooting

  • Incomplete API key: Paste the complete key from Mailchimp, including its server suffix.
  • HTTP 401 or 403: Check that the API key is valid and has access to the audience.
  • HTTP 404: Check the audience ID and whether it belongs to the API key's account.
  • HTTP 400: Check the email and merge fields, including custom fields required by your audience.
  • Pending contact: The contact still needs to confirm the double opt-in email.
  • Existing unsubscribed contact: Its status is deliberately preserved. Use Mailchimp's appropriate resubscription process.

Mailchimp's API quick start explains API keys and server prefixes. Its audience guide covers contact status and audience IDs.