Back for a new episode on FileMaker Integration with Web Services!
In the past three weeks we looked at what we need to integrate FileMaker with external APIs, and the code implementations for the Dropbox API and the Zendesk API.
Mailchimp
The idea for this series came while we were working on automating the process for our sponsorship program through FileMaker.
When someone signs up, we share a Dropbox folder with them (via web services), add them to our Zendesk support channel (via web services!) and then add them to our Mailchimp mailing lists, so that they can be notified when we release something new or we send out Beta updates. Having different Mailchimp lists for the different products, we want to add new members to the right one.
So this week we’ll look at this last step and the use of the Mailchimp API from a FileMaker file. Similarly to what we did for Dropbox and Zendesk, we use the BaseElements plugin to do HTTP calls inside a FileMaker script.
Looking at the Mailchimp API documentation we’ll see that every request type is defined by the HTTP method (GET, POST, PUT, DELETE, PATCH), the resource we want to work on (the endpoint) and the parameters of our request (the body). Let’s explain this with an example:
the two actions we want to perform from FileMaker are
- retrieve the information about the various Mailchimp Lists
- add a new member to the list we specify
The documentation for the first action tells us we will GET (HTTP method) the list of Lists sending a request to the /lists endpoint. No body parameters are needed.
For the second action we will need to POST our request to the /lists/{list_id}/members endpoint. In the body we’ll need to say what email we want to add and what status we want to assign to the new member.
The endpoints are relative to the base URL of the API, which for Mailchimp is
https://<dc>.api.mailchimp.com/3.0
The <dc> part identifies the data center for our account (more on this in a minute).
Mailchimp needs to know our system is authorised to interact with the account, otherwise everyone could change our Lists.
Authentication
The easiest way is to use HTTP Basic Auth creating an API key. The generated key can be used as the password for our requests.
Mailchimp doesn’t care about the username so any string will do.
The last part of the API key identifies the data center. In the image below the dc is us-13.
Get the Mailchimp Lists
The first request is to retrieve all the Mailchimp lists. As explained before, we need to send a GET request to the https://<dc>.api.mailchimp.com/3.0/lists endpoint with no parameters.
We can use the BaseElements plugin function BE_HTTP_GET to call the API
BE_HTTP_GET ( "https://anystring:TOKEN@<dc>.api.mailchimp.com/3.0/lists" )
A successful JSON response from the API will contain nodes for each one of the Lists
{
"lists": [
{
"id": "abc1234",
"name": "the BE people",
[...]
"stats": {
"member_count": 333,
"unsubscribe_count": 0,
"cleaned_count": 0,
[...]
},
[...]
},
{
"id": "xyz5678",
"name": "the RESTfm people",
[...]
"stats": {
"member_count": 222,
"unsubscribe_count": 0,
"cleaned_count": 0,
[...]
},
[...]
}
],
"total_items": 2
}we can use the BE_JSONPath function to extract th information we need from the returned JSON:
BE_JSONPath ( $json ; "$.lists[0].name" ) will return “the BE people”.
Add a new member to the list
In the Mailchimp API there are various ways to add a member to a list. The basic one is based on the /lists/{list_id}/members endpoint we talked about at the beginning of the article, while Batch Operations can be used to add multiple users at the same time.
A third method is to use a “create or update” function using the endpoint /lists/{list_id}/members/{subscriber_hash}.
We chose to use this method both for it’s flexibility and because it let’s us show a few details we didn’t use when working on the other APIs.
The first thing to notice is that the HTTP method is PUT, which is the one normally associated with updating.
Looking at the endpoint we need to clarify what the {subscriber_hash} part means: the API expected an MD5 hash of the lowercase version of the email. It’s a bit like a string identifying the email address.
To generate it we can use the BE_MessageDigest function from the BaseElements plugin:
BE_MessageDigest ( Lower("salvatore@goya.com.au"); BE_MessageDigestAlgorithm_MD5 ) will return B92A5EDE3BEDE58FEC9B0D473165475C (it’s not a secret code!).
We know the method and now we know the url of our request, the last thing missing is the body. The only two mandatory fields are the email address and the status (if creating a new member), but it’s always nice to also know the first and last name:
{
"email_address": "email" ,
"status_if_new": "subscribed",
"merge_fields": {
"FNAME": "fname",
"LNAME": "lname"
}
}Using BE_HTTP_PUT_DATA to send the request that becomes:
BE_HTTP_PUT_DATA ( "https://anystring:TOKEN@<dc>.api.mailchimp.com/3.0/lists/" & list_id & "/members/" & BE_MessageDigest ( Lower(email); BE_MessageDigestAlgorithm_MD5 ) ;
"{"email_address": ""& email &"", "status_if_new":"subscribed", "merge_fields": {"FNAME": "" & fname & "","LNAME": "" & lname & ""}}" )
A return code of HTTP 200 will mean everything went well and Mailchimp will send us back a unique ID for that member in Mailchimp.
Sample File
Once again, a complete example file is available to sponsors of the BaseElements plugin, along with previous examples for Dropbox and Zendesk.
Salvatore is our web services and integration expert, passionate about linking any API useful to our clients (or us!) to FileMaker. He loves to share ideas and a good story, and as a speaker at DevCon he manages to do both.