How to add "Tags" to mailchimp subscriber via the api

Question

Looking to add tags to my mailing list members via the api. But I don't see where to pass in tags in the documentation. Can someone point to an example of how to update the tags associated with a member via the api?

Solution 1

Tags replaced static segments. So, the endpoints used to create tags and add and remove tags from members are the same endpoints that were previously used to manage segments. Here is the documentation on the endpoints to use to manage your tags via the API that includes the request and response body parameters as well as example requests and responses:

http://developer.mailchimp.com/documentation/mailchimp/reference/lists/segments/

In order to add tags to your members, you need to include their email addresses in the 'static_segment' array parameter.

I hope that helps.

Solution 2

If you want to create a member AND add a tag while doing so you may specify the tag attribute the following way:

$data = array(
              'apikey'        => $api_key,
              'email_address' => $email,
              'status'     => $status,
              'tags'  => array('your-tag-name'),
              'merge_fields'  => array(
                    'FNAME' => $fname,
                    'LNAME' => $lname
                  )
            );

Even though MC API some places will tell you to fill out both a name and a status, it helped me to define tags as an array but ONLY pasting in the name of the tag.

Seefan's answer in this thread helped me out and I figured i wanted to help a person who spend days (like me) to figure out how the "tags" is specified: add tags to mailchimp subscriber created via api php

Solution 3

This is the official way to add tags: https://developer.mailchimp.com/documentation/mailchimp/reference/lists/members/tags/ It works, except that in my testing, the response message is empty, even though the tag is added.

Here's sample code in Google Apps Script:

payload = '{\
  "tags": [\
    {\
     "name":"' + tagName + '",\
     "status":"' + tagStatus + '"\
    }\
   ]\
}'
;

params = {
  "method": "POST",
  "headers":MC_headers,
  "payload": payload,
  "muteHttpExceptions": true
};
url = MC_url + 'lists/' + MC_IDs.listId + '/members/' + sub_hash + '/tags';
response = UrlFetchApp.fetch(url, params);

Solution 4

Apparently Mailchimp "tags" are "segments".

I coded a couple functions that allow me to add tags by name (rather than by ID) to a member (i.e. subscriber) by email address.

/**
 * 
 * @param string $emailAddress
 * @param array $tags
 * @return void
 */
public function addTagsToContact($emailAddress, $tags) {
    $list_id = $this->getDefaultListId();
    foreach ($tags as $tag) {
        $this->addMemberToSegment($emailAddress, $list_id, $tag);
    }
}

/**
 * Add a tag to a subscriber (tags replaced segments https://stackoverflow.com/a/52315577/470749)
 * 
 * @param string $emailAddress
 * @param string $list_id
 * @param string $segment_name
 * @return array
 */
public function addMemberToSegment($emailAddress, $list_id, $segment_name) {
    $api = Newsletter::getApi();
    $segmentsByName = $this->getSegments($list_id);
    $segment_id = $segmentsByName[$segment_name]['id'];
    $response = $api->post("lists/$list_id/segments/$segment_id", [
        'members_to_add' => [$emailAddress]
    ]); //https://developer.mailchimp.com/documentation/mailchimp/reference/lists/segments/#create-post_lists_list_id_segments_segment_id
    return $response;
}

/**
 * 
 * @param string $list_id
 * @return array
 */
public function getSegments($list_id) {//https://developer.mailchimp.com/documentation/mailchimp/reference/lists/segments/#%20
    $segmentsByName = [];
    $api = Newsletter::getApi();
    $count = 50; //default is 10
    $offset = 0;
    do {
        $url = "lists/$list_id/segments/?" . http_build_query(['count' => $count, 'offset' => $offset]);
        Log::debug($url);
        $response = $api->get($url);
        $total_items = $response['total_items'];
        foreach ($response['segments'] as $segment) {
            $segmentsByName[$segment['name']] = $segment;
        }
        $offset += $count;
    } while (count($segmentsByName) < $total_items);
    //Log::debug(json_encode($segmentsByName));
    return $segmentsByName;
}

/**
 * 
 * @return string
 */
public function getDefaultListId() {
    return config('newsletter.lists.subscribers.id');
}

This relies on the https://github.com/spatie/laravel-newsletter library.

P.S. Thanks so much to @Jelan, whose answer got me on the right track!

Solution 5

It took me a while to also figure this one out. Their documentation isn't clear and it seems there are 2 ways to add tags, either via the tags endpoint using POST or via the update user via a PATCH. Here's an example of the POST in PHP:

function tagUser($email){
global $api_key;
global $listId;
$hashedEmail = md5(strtolower($email));
$args = array(
    'method' => 'POST',
    'headers' => array(
        'Authorization' => 'Basic ' . base64_encode( 'user:'. $api_key )
    ),
    'body' => json_encode(array(
        'tags' => array(['name'=>'healthy','status'=>'active'])
    ))
);
$response = wp_remote_post( 'https://usxx.api.mailchimp.com/3.0/lists/'.$listId.'/members/'.$hashedEmail.'/tags', $args );

$body = json_decode( $response['body'] );

}

View more solutions

Comments

[Gerald]

You're welcome. I'm glad it helped. I gave a feedback to MailChimp to make the documentation clearer because it's not obvious that "tags" are "segments".

[Eaten by a Grue]

this is what I ended up with as well since it seems more straightforward than sending a request for each and every tag you want to modify for a given member. fyi, the http response code is "204 No Content - The server successfully processed the request and is not returning any content". So yes it's normal to receive no response. Something tells me they will either deprecate or enhance this method in a future version, it seems half baked.

[musicinmusic]

@billynoah is it possible to add multiple tags via only 1 request? Or do I have to make multiple requests to add multiple tags to a list member?

[musicinmusic]

For me the response code is "204 No Content" as well, but the tags was NOT added.

[DecimalTurn]

From my experience, this method works only when you add a new member, it won't work if you want to add tags to an existing member.

[Boris]

@DecimalTurn I use the same method to add a tag to an existing member as well.

[roadsunknown]

Discovered this too in the mess of the MailChimp documentation (mailchimp.com/developer/reference/lists/list-members) but wasn't exactly sure how to define the array (string name only, simple but not specified). This solution worked well for me as I already had the parent argument array defined. Thanks!

[RonE]

This worked for me! It's crazy that the docs say to also add a status tag when that's what was causing the error

[Gavin H]

I also had an issue with a 204 response code but the tags not added. In my case it was because I had a trailing comma in the list of tag objects. I removed the trailing comma and still got a 204 response but it worked that time.

[globalSchmidt]

It's 2022... I too tried to add a contact with tags using the [["name" => "tag1", "status" => "active"]] approach without success. This solution (no status key/value) worked. Also to add multiple tags (not explicitly stated), simply use "tags" => ["tag1", "tag2", "tag3"].

[Christian Hagelid]

The tags property exists on the POST endpoint but it seems to be missing from the PUT (upsert) endpoint? mailchimp.com/developer/marketing/api/list-members/…. I wanted to use that to avoid having to make a GET request first. Ideally I'd like to add a tag to new subscribers only (add tag on insert but not on update). Is that possible without making a series of API calls?