Patch & Put Requests

Patch Requests

A patch request is made when we want to alter an existing resource in MailChimp. Within the context of this library they syntactically behave like post requests in that the patch() method only takes in one argument being the parameters you wish to serialize and send to MailChimp, and similar to POST requests you should be wary not to send a request without any required params.

You can review POST requests here: https://github.com/Jhut89/Mailchimp-API-3.0-PHP/wiki/Post-Requests

Let take the subscriber that we created in our POST example and try to add some data surrounding that contact into MailChimp. if you remember the response we got back when posting our subscriber looked like this:

{
  "id": "852aaa9532cb36adfb5e9fef7a4206a9",
  "email_address": "urist.mcvankab+3@freddiesjokes.com",
  "unique_email_id": "fab20fa03d",
  "email_type": "html",
  "status": "subscribed",
  "status_if_new": "",
  "merge_fields": {
    "FNAME": "",
    "LNAME": ""
  },
  "interests": {
    "9143cf3bd1": false,
    "3a2a927344": false,
    "f9c8f5f0ff": false,
    "f231b09abc": false,
    "bd6e66465f": false
  },
  "stats": {
    "avg_open_rate": 0,
    "avg_click_rate": 0
  },
  "ip_signup": "",
  "timestamp_signup": "",
  "ip_opt": "198.2.191.34",
  "timestamp_opt": "2015-09-16 19:24:29",
  "member_rating": 2,
  "last_changed": "2015-09-16 19:24:29",
  "language": "",
  "vip": false,
  "email_client": "",
  "location": {
    "latitude": 0,
    "longitude": 0,
    "gmtoff": 0,
    "dstoff": 0,
    "country_code": "",
    "timezone": ""
  },
  "list_id": "57afe96172",
  "_links": [...]
}

We can see that this subscriber has no associated first name (FNAME) or last name (LNAME) data. We can add those using the patch() method. Like this:

$patch_params = [
    "merge_fields" => [
        "FNAME" => "Urist",
        "LNAME" => "Mcvankab"
    ]
]
 
$patch_response = $mailchimp
                    ->lists($list_id)
                    ->members("urist.mcvankab+3@freddiesjokes.com")
                    ->patch($patch_params);

There are a couple of things to note here. One is that we did not provide the members() method with a member_id rather we provided an email address instead. Because a member_id is just the md5 hash of the lowercase email address this library can translate these for your program and the MailChimp API. Alternatively a member_id can be provided an this library will know not to hash it. This is the case with any method whose argument is a member_id.

The response body we should then see from MailChimp should look like the one above only now we should see this in the response:

"merge_fields": {
  "FNAME": "Urist",
  "LNAME": "Mcvankab"
}

Put Requests

A PUT request is made when we do not know if a resource exists yet in MailChimp, and if it does we want to update it, otherwise we want to create it. As with both PATCH & POST we should be cautious not to send a request without its required parameters. Let's go ahead and walk through making a PUT request to a list member with a first and last name in their merge fields. We know from the MailChimp docs that there are two required parameters for a put request against this resource, email_address & status_if_new. From this we know our request should look like this:

$put_params = [
    "email_address" => "hutch@exampledomain.com",
    "status_if_new" => "subscribed",
    "merge_fields" => [
        "FNAME" => "hutch",
        "LNAME" => "hutcheson"
    ]
];

$put_response = $mailchimp
                    ->lists($list_id)
                    ->members("hutch@exampledomain.com")
                    ->put($put_params);

If our request is successful we should see a response body from MailChimp that looks similar to:

{
  "id": "206021acb391b3514f90ef6b53134619",
  "email_address": "hutch@exampledomain.com",
  "unique_email_id": "fab20fa03d",
  "email_type": "html",
  "status": "subscribed",
  "status_if_new": "",
  "merge_fields": {
    "FNAME": "hutch",
    "LNAME": "hutcheson"
  },
  "interests": {
    "9143cf3bd1": false,
    "3a2a927344": false,
    "f9c8f5f0ff": false,
    "f231b09abc": false,
    "bd6e66465f": false
  },
  "stats": {
    "avg_open_rate": 0,
    "avg_click_rate": 0
  },
  "ip_signup": "",
  "timestamp_signup": "",
  "ip_opt": "198.2.191.34",
  "timestamp_opt": "2015-09-16 19:24:29",
  "member_rating": 2,
  "last_changed": "2015-09-16 19:24:29",
  "language": "",
  "vip": false,
  "email_client": "",
  "location": {
    "latitude": 0,
    "longitude": 0,
    "gmtoff": 0,
    "dstoff": 0,
    "country_code": "",
    "timezone": ""
  },
  "list_id": "57afe96172",
  "_links": [...]
}