Getting Started | Campaign Monitor

We recommend that you get started with our API by using an API wrapper in the language of your choice. Whether you choose to use a wrapper or not, this guide includes all the details you need to start building things.

Grab a Wrapper

Our API wrappers are going to make your job much easier. Right now we have wrappers available for Ruby, Python, PHP, Java, .NET, Perl, and Objective-C 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.

For lots of you, having an API wrapper and its accompanying documentation will be enough to get started. Next up, select the area of the API you'd like to work with (such as Account, Campaigns, Clients, etc) from the menu above. For those looking at rolling their own solution or interested in learning more about how the API works, we've expanded on that below.

Authentication

The Campaign Monitor API currently supports two methods of authentication. We recommend authenticating with OAuth, however we also support authenticating with an API key.

Authenticating with OAuth

We use the OAuth 2 protocol to allow websites or applications to request authorization to a Campaign Monitor account without requiring the account username and password. Authenticating using OAuth is preferred over using an API key with Basic Authentication.

Register an Application

To authenticate using OAuth, you're going to need to register an OAuth Application. To do this, jump into your Campaign Monitor account, go to Account Settings, then select Manage connected apps on the right hand side. From there you'll be asked for a few details to register your OAuth app.

Once you've registered your app, it will be assigned a unique Client ID and Client Secret. You'll need to specify these two details when using our API wrappers (which is recommended), or if you're not going to use an API wrapper, you'll need these details when your application requests access tokens (details below).

Permissions

Any application which authenticates using OAuth must specify which permissions it requires when requesting access tokens. All valid permissions are listed below. You'll need to refer to these permissions when you follow the authentication flows described below.

ViewReports Permission to view reports.
ManageLists Permission to manage lists.
CreateCampaigns Permission to create campaigns.
ImportSubscribers Permission to import subscribers.
SendCampaigns Permission to send campaigns.
ViewSubscribersInReports Permission to view subscribers in reports.
ManageTemplates Permission to manage templates.
AdministerPersons Permission to administer persons.
AdministerAccount Permission to administer your account.

Web Application Flow

These are the steps for authenticating from a web application.

1. Direct users of your application to:

https://api.createsend.com/oauth?type=web_server&client_id={client_id}&redirect_uri={redirect_uri}&scope={scope}&state={state}

Details of query string parameters:

type REQUIRED - MUST be web_server
client_id REQUIRED - The Client ID you received when you registered your application.
redirect_uri REQUIRED - Where we will redirect your users once the OAuth call is made. This must start with the redirect URI provided when you registered your application.
scope REQUIRED - The permission level requested by the integration.
This is a comma separated list of valid permissions as documented above. So for example, if you wanted to request permission to send campaigns and view reports, you would provide scope as SendCampaigns,ViewReports (which, when URL-encoded would be SendCampaigns%2CViewReports)
state OPTIONAL - Any additional state to be included in the redirection call.

2. The user of your application approves (or doesn't approve) your application.

3. The user of your application is redirected to the redirect_uri with the following query string parameters:

code A unique code generated by Campaign Monitor.
state Any state data provided in step 1.

4. Your application should then make a POST request to the following URL:

https://api.createsend.com/oauth/token

Including the following data:

grant_type=authorization_code&client_id={client_id}&client_secret={client_secret}&code={code}&redirect_uri={redirect_uri}

Details of POST data:

grant_type Must be authorization_code
client_id The client_id as per step 1.
client_secret This must be the secret you received when you registered your application.
code The code as per step 3.
redirect_uri The redirect_uri as per step 1.

The response to this POST request will be a JSON object of the form:

{
    "access_token": "SlAV32hkKG",
    "expires_in": 1209600,
    "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
}

Details of the response data:

access_token The OAuth token to use for further API calls.
expires_in The number of seconds for which access_token is valid.
refresh_token A long-lived token which can be used to obtain a new access token.

So for example, if your application initiated an OAuth exchange by directing a user to:

https://api.createsend.com/oauth?type=web_server&client_id=1&redirect_uri=https%3A%2F%2Fsender.example.com%2Fintegrate&scope=CreateCampaigns%2CSendCampaigns%2CViewReports&state=somedata

Assuming the user approved your application, Campaign Monitor would then redirect your user to:

https://sender.example.com/integrate?code=abc123&state=somedata

Upon receiving this request, your application should then make a POST request to the following URL:

https://api.createsend.com/oauth/token

Including the following data:

grant_type=authorization_code&client_id=1&client_secret=hanshotfirst&code=abc123&redirect_uri=https%3A%2F%2Fsender.example.com%2Fintegrate

This request would then result in the following JSON response:

{
    "access_token": "SlAV32hkKG",
    "expires_in": 1209600,
    "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
}

Non-Web Application Flow

These are the steps for authenticating from desktop or other applications.

1. Direct users of your application to:

https://api.createsend.com/oauth?type=user_agent&client_id={client_id}&redirect_uri={redirect_uri}&scope={scope}

Details of query string parameters:

type REQUIRED - MUST be user_agent
client_id REQUIRED - The Client ID you received when you registered your application.
redirect_uri REQUIRED - Where we will redirect your users once the OAuth call is made. This must start with the redirect URI provided when you registered your application.
scope REQUIRED - The permission level requested by the integration.

2. The user of your application approves (or doesn't approve) your application.

3. The user of your application is redirected to the redirect_uri with the following parameters in the hash of the URL:

access_token The OAuth access token to use for further API calls.
expires_in The number of seconds for which access_token is valid.

So for example, if your application initiated an OAuth exchange by directing a user to:

https://api.createsend.com/oauth?type=user_agent&client_id=1&redirect_uri=https%3A%2F%2Fsender.example.com%2Fintegrate&scope=CreateCampaigns%2CSendCampaigns%2CViewReports

Assuming the user approved your application, Campaign Monitor would then redirect your user to:

https://sender.example.com/integrate#access_token=abc123&expires_in=1209600

Errors during OAuth exchange

Error handling within the oAuth exchange depends on the type of error encountered. Errors related to end-user information (credentials, permissions etc) are shown to the end-user during the oAuth exchange, errors related to the integration will result in the end-user being sent to the redirect_uri with the details of the error included.

Possible integration errors are:

invalid_request Required parameters were not supplied.
unknown_client The client_id did not match a registered integration.
invalid_redirect_uri The redirect_uri did not begin with the redirect URI registered for the application.
server_error Something went wrong at the Campaign Monitor end.
unknown_scope Unrecognised permissions were requested via the scope parameter.
access_denied The end-user did not grant authorisation.

Possible end-user errors are:

Invalid credentials.
Insufficient permissions - The end-user did not have the permissions required by the integration.

Notes on the Redirect URI

A redirect URI must be a sub-URI of the redirect URI value entered when you registered your application. This means that the redirect URI must start with the redirect URI of your application (scheme, authority, and any path elements must match).

Refreshing Access Tokens

All access tokens granted will automatically expire after the timeframe specified when retrieving the token, so all developer code must cater for refreshing tokens.

If an access token has been granted using the Web Application Flow, you can use the refresh token included when the original token was granted to automatically retrieve a new access token. You do this by issuing a POST request to the following URL:

https://api.createsend.com/oauth/token

Including the following data:

grant_type=refresh_token&refresh_token={refresh_token}

Details of POST data:

grant_type REQUIRED - MUST be refresh_token
refresh_token REQUIRED - The refresh_token supplied during the previous token grant

The response to these refresh token requests takes the same form as the response to the initial token grant:

{
    "access_token": "SlAV32hkKG",
    "expires_in": 1209600,
    "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
}

If an access token has been granted using the Non-Web Application Flow, you do not receive a refresh token when you are granted an access token. In this situation, your code will need to use the expires_in value provided in the hash of the URL, to calculate whether you need to request a new access token if the current token has expired.

Using access tokens to make API calls

When making API calls with an OAuth access token, the token should be passed in as a bearer token in the Authorization header of an API request.

So for example, if your access token was MDRmODIzNTBhODQ1ZWU5ZDkz, the authorization header of your HTTP requests would be Authorization: Bearer MDRmODIzNTBhODQ1ZWU5ZDkz.

To get a list of your clients in JSON format using cURL, you'd do the following:

curl -H "Authorization: Bearer MDRmODIzNTBhODQ1ZWU5ZDkz" https://api.createsend.com/api/v3/clients.json?pretty=true

Response You should receive a HTTP response similar to:


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

Authenticating with an API key

You may also use an API key and HTTP Basic Authentication to authenticate API requests. You can get your API key from the Account Settings page when logged into your Campaign Monitor account. 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 authentication.

To demonstrate authentication with an API key, 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:

https://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 'x'. If your request is authenticated, you should then be delivered the JSON response.

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

To get a list of your clients in JSON format using cURL, you'd do the following:

curl -u "dklkmwlmkdy7qwd98y98y98y8d68d9:x" https://api.createsend.com/api/v3/clients.json?pretty=true

Response You should receive a HTTP response similar to:


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

Your Client ID

Some API calls require the ID of a specific client in your account. 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:

Your List ID

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

Input & Output

Input and output is currently supported in XML and JSON. When you make an API request, you must specify a data format in the route, which represents both the data format in which you are providing input in the body of the request (only relevant to POST and PUT requests) and also the format in which you expect to receive output in the body of the response. The format is specified using either a .json or .xml portion in the route, as illustrated below.

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:

POSThttps://api.createsend.com/api/v3/clients.xml

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

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

POSThttps://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:

GEThttps://api.createsend.com/api/v3/clients.xml

<?xml version="1.0" encoding="utf-8"?>
<Clients>

	<Client>
		<ClientID>4a397ccaaa55eb4e6aa1221e1e2d7122</ClientID>
		<Name>Client One</Name>
	</Client>
	<Client>
		<ClientID>a206def0582eec7dae47d937a4109cb2</ClientID>
		<Name>Client Two</Name>
	</Client>

</Clients>

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:

GEThttps://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 OAuth token, you'll receive one of the following "401 Unauthorized" responses. See the Authenticating with OAuth section about how to request or renew an access token.