---
ref: tool:mailchimp/upsert-list-member
name: Create or update a contact
company: company:mailchimp
workflows: []
access: [api]
tags: [capability:build-audience, category:email, has:api]
docs: https://mailchimp.com/developer/marketing/api/list-members/add-or-update-list-member/
updated: 2026-09-27
---

# Create or update a contact

Adds a contact to an audience or updates the contact with that email address, with its subscription status and merge fields.

Note: `{subscriber_hash}` is the MD5 hash of the lowercase email address, or the address itself. `email_address` and `status_if_new` take effect only when the contact is new.

## Set up

Use the first option your agent supports.

### API (official)

- Base URL: https://{dc}.api.mailchimp.com/3.0
- Endpoint: `PUT /lists/{list_id}/members/{subscriber_hash}`
- Auth: send the header `Authorization: Bearer $MAILCHIMP_API_KEY`
- Get a key: https://us1.admin.mailchimp.com/account/api/
- Docs: https://mailchimp.com/developer/marketing/api/

Note: `{dc}` is your data center, the part of the API key after the dash, such as `us6`.

Before anything else, confirm access with the cheapest read-only call, like a list or a search. Never send or change anything to test access.

## Rules

- Ask the user before anything that sends messages, costs money, or changes data, and say how many records it touches. One approval covers a batch the user has seen.
- Never print API keys.