API Documentation

Grab a wrapper

Our wrappers are going to make your job so much easier. Right now we have wrappers available for Ruby, Python, PHP, Java, .NET and Perl that cover all of the functionality available in the API and make it a cinch to work with. No really, go and grab one now, then head back here.

Find your API key

You can find your API key by logging into your account and clicking on the "Account Settings" link in the top left of your screen. If you haven't already done so, you'll need to click the "Generate your API key" link on the right side of the page. After that, just click the big "Generate my API key button".

Once your key is generated, it can be found at the bottom of the same page and will look something like this:

For lots of you, having the wrapper of choice at your disposal and your API key will be enough to get started. next up, select the area of the API you'd like to work with (such as subscribers, campaigns, etc) in the menu on the left. For those looking at rolling their own solution or interested in learning more about how the API works, we've expanded on that below.

Your Client ID

Some API calls require the ID of a specific client. You can find this via the "Getting your clients" method in the API, or head into "Client Settings" for any client in your account and you'll find it here:

Before your client ID appears in your "Client Settings", you must have first generated your API key.

Your List ID

You can find any list ID via the List details link to "Getting List ID" method, or by heading into any list in your account and clicking the "change name/type" link below your list name.

Authentication

The Campaign Monitor API uses HTTP Basic Authentication to authenticate requests. When you make an API request you provide your API key as the username and the password portion can be blank or a dummy value, as it is not used for API authentication.

To demonstrate authentication with the API, you can make any GET request to the API directly in your web browser. So for example, if you wanted to get a list of all your clients in JSON format, you would enter the following into your address bar:

                    http://api.createsend.com/api/v3/clients.json
                  

Your browser should then display a dialog requesting that you enter a username and password. Enter your API key (e.g. "dklkmwlmkdy7qwd98y98y98y8d68d9") in the username field. You can leave the password field blank or enter a dummy value like "magic". If your request is authenticated, you should then be delivered the JSON response.

You are also able to test calls using a command line tool like cURL (which will also allow you to make requests which require the use of the POST, PUT and DELETE HTTP verbs).

This is the equivalent way of authenticating using cURL, rather than your web browser:

                    curl -u "dklkmwlmkdy7qwd98y98y98y8d68d9:magic" http://api.createsend.com/api/v3/clients.json -v
                  

                    > GET /api/v3/clients.json HTTP/1.1
                    > Authorization: Basic MDRmODIzNTBhODQ1ZWU5ZDkzN2Y3ODIwOTEwMTVhMDA6eA==
                    > User-Agent: curl/7.19.7 (universal-apple-darwin10.0) libcurl/7.19.7 OpenSSL/0.9.8l zlib/1.2.3
                    > Host: api.createsend.com:80
                    > Accept: */*
                  

                    < HTTP/1.1 200 OK
                    < Cache-Control: private, s-maxage=0
                    < Content-Type: application/json; charset=utf-8
                    < Server: Microsoft-IIS/7.5
                    < X-AspNetMvc-Version: 2.0
                    < X-AspNet-Version: 2.0.50727
                    < X-Powered-By: ASP.NET
                    < Date: Thu, 16 Sep 2010 06:33:42 GMT
                    < Content-Length: 1168

                    [{"ClientID":"4a397ccaaa55eb4e6aa1221e1e2d7122","Name":"Client One"},{"ClientID":"a206def0582eec7dae47d937a4109cb2","Name":"Client Two"}]
                  

Input & Output

Input and output is currently supported in XML and JSON. When you make an API request, you must specify a data format as part of the route, which represents both the data format in which you are sending content in the body of the request (this is only required for specific POST and PUT requests) and also the format in which you expect to receive output in the body of the response. The format is always specifed as the last portion of the API request route, as illustrated below (either ".json" or ".xml").

When providing input you must ensure that your XML is well-formed or your JSON complies with the syntax paying particular attention to character and entity encoding with both formats. Any input provided in the query string of any request should be url-encoded. An example of where this is required is the request for getting a subscriber's details which takes an email address as a query string parameter.

Providing input

Example Creating a client

To create a client using XML as the input data format, you would make a HTTP POST request as follows:

To create a client using JSON as the input data format, you would make a HTTP POST request as follows:

                    {
                      "CompanyName": "Client Company Three",
                      "ContactName": "Client Three",
                      "EmailAddress": "client3@example.com",
                      "TimeZone": "(GMT+10:00) Canberra, Melbourne, Sydney",
                      "Country": "Australia"
                    }
                  

Getting output

Example Getting a list of clients

To get a list of clients in XML format, you would make a HTTP GET request using the xml extension. You'll receive a response in XML format similar to the following:

The Content-Type header of the response will be set to "application/xml; charset=utf-8".

To get a list of clients in JSON format, you would make a HTTP GET request using the json extension. You'll receive a response in JSON format similar to the following:

                    [ 
                      {
                        "ClientID": "4a397ccaaa55eb4e6aa1221e1e2d7122",
                        "Name": "Client One"
                      },
                      {
                        "ClientID": "a206def0582eec7dae47d937a4109cb2",
                        "Name": "Client Two"
                      }
                    ]
                  

The Content-Type header of the response will be set to "application/json; charset=utf-8".

Response status codes

The responses returned by the API are accompanied by meaningful HTTP status codes which represent the status of the request. Here's the general approach we take when returning responses:

Success:

• GET

  requests will return a "200 OK" response if the resource is successfully retrieved.

• POST

  requests which create a resource we will return a "201 Created" response if successful.

• POST

  requests which perform some other action such as sending a campaign will return a "200 OK" response if successful.

• PUT

  requests will return a "200 OK" response if the resource is successfully updated.

• DELETE

  requests will return a "200 OK" response if the resource is successfully deleted.

Errors:

If you attempt to authenticate with an invalid API key or you attempt to use an invalid ID for a resource, you'll received a "401 Unauthorized" response.

                    {
                      "Code": 102,
                      "Message": "Invalid ClientID"
                    }
                  

If there is an error in your input, you'll receive a "400 Bad Request" response, with details of the error.

                    {
                      "Code": 250,
                      "Message": "List title must be unique within a client"
                    }
                  

If you attempt to request a resource which doesn't exist, you'll receive a "404 Not Found" response.

                    {
                      "Code": 404,
                      "Message": "We couldn't find the resource you're looking for. Please check the documentation and try again"
                    }
                  

If an unhandled error occurs on the API server for some reason, you'll receive a "500 Internal Server Error" response.

                    {
                      "Code": 500,
                      "Message": "Sorry, we've run into a problem. Please try again or contact support"
                    }
                  

Secure Access

All API requests can be made using either http or https. We do not enforce the use of https on any requests, though we do highly recommend that you use https for all requests if possible.

Making things pretty

You can add pretty=true to the query string of any request if you want the output to be indented in a nice human-readable format.

So, the following request without the pretty parameter:

                    http://api.createsend.com/api/v3/clients.json
                  

would produce output similar to:

                  [{"ClientID":"4a397ccaaa55eb4e6aa1221e1e2d7122","Name":"Client One"},{"ClientID":"a206def0582eec7dae47d937a4109cb2","Name":"Client Two"}]
                

And, the following request including pretty=true:

                    http://api.createsend.com/api/v3/clients.json?pretty=true
                  

would produce output similar to:

                  [
                    {
                      "ClientID": "4a397ccaaa55eb4e6aa1221e1e2d7122",
                      "Name": "Client One"
                    },
                    {
                      "ClientID": "a206def0582eec7dae47d937a4109cb2",
                      "Name": "Client Two"
                    }
                  ]