Getting Started
By far the easiest way to start working with our API is to use the wrapper for your language of choice. They take care of most of the heavy lifting for you. Once you've downloaded the wrapper, the next thing you'll need is your API key.
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
Your HTTP request should look similar to:
> 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: */*
And you should receive a HTTP response similar to:
< 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:
POST http://api.createsend.com/api/v3/clients.xml
To create a client using JSON as the input data format, you would make a HTTP POST request as follows:
POST http://api.createsend.com/api/v3/clients.json
{
"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:
GET http://api.createsend.com/api/v3/clients.xml
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:
GET http://api.createsend.com/api/v3/clients.json
[
{
"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.
If there is an error in your input, you'll receive a "400 Bad Request" response, with details of the error.
Example response body: 400 Bad Request
JSON
XML
{
"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.
Response body: 404 Not Found
JSON
XML
{
"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.
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"
}
]