Skip to navigation
API ReferenceLists

Add or update list member

Add or update a list member.

Authentication

AuthorizationBearer

Authorization using a Mailchimp API key (a.k.a. Bearer token)

OR
AuthorizationBearer
Authorization using OAuth

Path parameters

list_idstringRequired
The unique ID for the list.
subscriber_hashstringRequired

The MD5 hash of the lowercase version of the list member's email address. This endpoint also accepts a list member's email address or contact_id.

Query parameters

skip_merge_validationbooleanOptional

If skip_merge_validation is true, member data will be accepted without merge field values, even if the merge field is usually required. This defaults to false.

Request

Individuals who are currently or have been previously subscribed to this list, including members who have bounced or unsubscribed.
email_addressstringRequired
Email address for a subscriber. This value is required only if the email address is not already present on the list.
email_typestringOptional

Type of email this member asked to get ('html' or 'text').

interestsmap from strings to booleansOptional
The key of this object's properties is the ID of the interest in question.
ip_optstringOptional

The IP address the subscriber used to confirm their opt-in status.

ip_signupstringOptional
IP address the subscriber signed up from.
languagestringOptional

If set/detected, the subscriber's language.

locationobjectOptional
Subscriber location information.
marketing_permissionslist of objectsOptional
The marketing permissions for the subscriber.
merge_fieldsmap from strings to objects or strings or doublesOptional

A dictionary of merge fields where the keys are the merge tags. See the Merge Fields documentation for more about the structure.

statusenumOptional
Subscriber's current status.
Allowed values:
status_if_newenumOptional
Subscriber's status. This value is required only if the email address is not already present on the list.
Allowed values:
tagslist of stringsOptional
The tags that are associated with a member.
timestamp_optstring or enumOptional
timestamp_signupstring or enumOptional
vipbooleanOptional

VIP status for subscriber.

Response

This endpoint returns an object.
consents_to_one_to_one_messagingbooleanOptionalRead-only

Indicates whether a contact consents to 1:1 messaging.

contact_idstringOptionalRead-only

As Mailchimp evolves beyond email, you may eventually have contacts without email addresses. While the id is the MD5 hash of their email address, this contact_id is agnostic of contact’s inclusion of an email address.

email_addressstringOptional
Email address for a subscriber.
email_clientstringOptionalRead-only
The list member's email client.
email_typeanyOptional

Type of email this member asked to get ('html' or 'text').

idstringOptionalRead-only
The MD5 hash of the lowercase version of the list member's email address.
interestsmap from strings to booleansOptional
The key of this object's properties is the ID of the interest in question.
ip_optstringOptionalRead-only

The IP address the subscriber used to confirm their opt-in status.

ip_signupstringOptionalRead-only
IP address the subscriber signed up from.
languagestringOptional

If set/detected, the subscriber's language.

last_changeddatetimeOptionalRead-only
The date and time the member's info was last changed in ISO 8601 format.
last_noteobjectOptionalRead-only
The most recent Note added about this member.
list_idstringOptionalRead-only
The list id.
locationobjectOptional
Subscriber location information.
marketing_permissionslist of objectsOptional
The marketing permissions for the subscriber.
member_ratingintegerOptionalRead-only
Star rating for this member, between 1 and 5.
merge_fieldsmap from strings to objects or strings or doubles or nullOptional

A dictionary of merge fields where the keys are the merge tags. See the Merge Fields documentation for more about the structure.

sms_phone_numberstringOptional
A US phone number for SMS contact.
sms_subscription_last_updatedstringOptional
The datetime when the SMS subscription was last updated
sms_subscription_statusenumOptional
The status of an SMS subscription.
Allowed values:
sourcestringOptionalRead-only
The source from which the subscriber was added to this list.
statsobjectOptionalRead-only
Open and click rates for this subscriber.
statusenumOptional
Subscriber's current status.
tagslist of objectsOptional

Returns up to 50 tags applied to this member. To retrieve all tags see Member Tags.

tags_countintegerOptionalRead-only
The number of tags applied to this member.
timestamp_optdatetimeOptionalRead-only

The date and time the subscriber confirmed their opt-in status in ISO 8601 format.

timestamp_signupdatetimeOptionalRead-only
The date and time the subscriber signed up for the list in ISO 8601 format.
unique_email_idstringOptionalRead-only
An identifier for the address across all of Mailchimp.
unsubscribe_reasonstringOptional
A subscriber's reason for unsubscribing.
vipbooleanOptional

VIP status for subscriber.

web_idintegerOptionalRead-only

The ID used in the Mailchimp web application. View this member in your Mailchimp account at https://{dc}.admin.mailchimp.com/lists/members/view?id={web_id}.