I have just started playing with the MailChimp API with Coldfusion. As usual, there’s not a lot of Coldfusion documentation or examples. So I thought I’d start posting some of the how-to’s as I myself figure them out. Here will demonstrate how to make a simple connection with the API so you can start doing more productive things like adding emails to lists and getting stats.

Let’s begin at the beginning of using any API. We need an account and an API key. Go ahead and create an account as if you’re a client, or if you are doing this for an actual client go ahead and create an account for them. MailChimp makes this super simple. Once you have an account click on the ‘account’ button in the top left corner of the dashboard. This will take you to a set of links. Click the ‘API Keys & Info’ link. This will take you to a page where you can manage your API keys. Clicking ‘Add A Key’ will generate a new key for you to use.

Now that we have our key and account we’re ready to make our connection via Coldfusion. Before looking at any code, let’s make sure we know where our documentation is at. You can find the MailChimp docs here. Requesting data from MailChimp requires you to pass the method and parameters via the url: http://us1.api.mailchimp.com/1.2/. As parameters you need to indicate the type of output MailChimp should return data as. In our case we’ll use JSON. So we’ll attach ‘?output=json’. Next we need to specify the method. MailChimp has a ping() method meant for no other reason than to make sure the connection is working. So this is what we’ll use here. To do this we attach the method parameter ‘&method=ping’. If you look at the docs you’ll see that this requires only one parameter to work, which is the API key (this is required for all methods). So we’ll attach another parameter ‘&apikey=[yourapikey]‘.

So let’s look at how to write this using Coldfusion.

<!--- SET URL --->
<cfset VARIABLES.api_url = "http://us1.api.mailchimp.com/1.2/?output=json&method=ping&apikey=[your key]-us1">

<!--- SEND DATA VIA CFHTTP TAG --->
<cfhttp name="call" url="#VARIABLES.api_url#" result="VARIABLES.mycall">

<!--- BECAUSE RETURNED AS JSON WE NEED TO DESERIALIZE THE RESPONSE --->
<cfset VARIABLES.deserialized = deserializeJSON(VARIABLES.mycall.fileContent)>

<!--- DUMP RESPONSE --->
<cfdump var="#VARIABLES.deserialized#">

First we set our URL. In this case you’ll, of course, change the ‘[your key]‘ to whatever your actual key is that MailChimp generated for you in your account. Next we use the Coldfusion tag to send the url to MailChimp. MailChimp then processes it and sends back the result which we store as ‘VARIABLES.mycall’. Because we specified to MailChimp to return data back to us as JSON we need to make sure we deserialize it before displaying it. We do this using the ‘deserializeJSON()’ method. Also the response is passed back as a struct with the actual data from MailChimp stored in the ‘fileContent’ key. Lastly we just dump the data so we can see that ‘Everything’s Chimpy!’.

At this point you should be able to start playing more with the API to do more complex and practical things.