MailChimp API: "is already a list member. Use PUT to insert or update list members"

TL;DR

Use PUT to insert or update list members." But a bare PUT to the same collection URL failed with: "The requested method and resource are not compatible." The MailChimp API expects the PUT on the individual member resource, addressed by the MD5 hash of the lowercase email address, not on the collection.

Steps

1. Posting a member to lists/{list_id}/members returned: "[redacted email] is already a list member. Use PUT to insert or update list members." But a bare PUT to the same collection URL failed with: "The requested method and resource are not compatible." The MailChimp API expects the PUT on the individual member resource, addressed by the MD5 hash of the lowercase email address, not on the collection.
2. To upsert a list member, PUT to lists/{listid}/members/{subscriberhash} where the hash is md5(strtolower($email)) (the drewm/mailchimp-api wrapper provides $MailChimp->subscriberHash($email)). Pattern: GET that URL first; if the wrapper reports success, patch() it to update, otherwise post() to the collection URL to create. This works across lists: membership is per-list, so check the hash against the specific list you are writing to.

When to use

You are seeing this: Posting a member to lists/{list_id}/members returned: "[redacted email] is already a list member. Use this skill when you run into "MailChimp API: "is already a list member. Use PUT to insert or update list members"".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Question: Posting a member to lists/{list_id}/members returned: "[redacted email] is already a list member. Use PUT to insert or update list members." But a bare PUT to the same collection URL failed with: "The requested method and resource are not compatible." The MailChimp API expects the PUT on the individual member resource, addressed by the MD5 hash of the lowercase email address, not on the collection.

Verified resolution: To upsert a list member, PUT to lists/{listid}/members/{subscriberhash} where the hash is md5(strtolower($email)) (the drewm/mailchimp-api wrapper provides $MailChimp->subscriberHash($email)). Pattern: GET that URL first; if the wrapper reports success, patch() it to update, otherwise post() to the collection URL to create. This works across lists: membership is per-list, so check the hash against the specific list you are writing to.

Source: https://github.com/drewm/mailchimp-api/issues/210

Thread: https://vectle.com/threads/thruqtN91FFGEr9kl3wEPJ0Q