Our API

Webhooks

Webhooks come in handy for keeping your subscribers in sync. Instead of having to poll our API constantly to check for updates, we'll let you know the instant a change has been made. This might be someone unsubscribing, joining your list, changing their email address and more.


What's a Webhook?

A webhook is simply a user-defined callback in the form of an HTTP POST, which is invoked when something happens.

For example, when someone subscribes to one of your Campaign Monitor lists, you might like the data about that subscription to be made available to another application. You can do this by simply specifying a URL to which that data should be sent when the subscription occurs.

Using this example of someone subscribing to your list, here's an example of the data we'll post in the body of an HTTP POST request to the URL you've specified. We can send this to you in either xml or json, depending on what's most useful to you.

Example of the data in the HTTP POST to your URL on subscription: JSON XML
{
    "Events": [
        {
            "CustomFields": [
                {
                    "Key": "website", 
                    "Value": "http:\/\/example.org"
                }
            ],
            "Date": "2010-12-14 11:32:00",
            "EmailAddress": "test@example.org",
            "Name": "Test Subscriber",
            "SignupIPAddress": "53.78.123.243",
            "Type": "Subscribe"
        }
    ],
    "ListID": "96c0bbdaa54760c8d9e62a2b7ffa2e13"
}

So all you need to do is process this data being received at your URL.


Batching events

To minimise the number of HTTP POST requests we make to your URLs, we batch events together into the request body when possible.

For example, if you manually enter two new subscribers through the Campaign Monitor app, we'd make one HTTP POST request to your URL, including data similar to the following.

Batching two subscribe events together in the body of the HTTP POST to your URL: JSON XML
{
    "Events": [
        {
            "CustomFields": [],
            "Date": "2010-12-14 11:32:00",
            "EmailAddress": "testone@example.org",
            "Name": "Test One Subscriber",
            "SignupIPAddress": "TypeManual",
            "Type": "Subscribe"
        },
        {
            "CustomFields": [],
            "Date": "2010-12-14 11:32:00",
            "EmailAddress": "testtwo@example.org",
            "Name": "Test Two Subscriber",
            "SignupIPAddress": "TypeManual",
            "Type": "Subscribe"
        }
    ],
    "ListID": "96c0bbdaa54760c8d9e62a2b7ffa2e13"
}

We'll batch a maximum of 1,000 events at a time, at the rate of one batch every 10 seconds. This means that for an import of a new list of 6,500 subscribers, over the course of around a minute you'll receive seven POST requests, the first six with 1,000 subscribe events, and the last with 500.


Handling request failures

To ensure we don't continue to hit a URL that is experiencing a problem, we've built some simple failure handling into our webhooks functionality.

If we see sustained errors on a request for more than a week, we will automatically deactivate that webhook for you. This limit is something we've set initially, but that may change based on customer feedback if it's too sensitive. Don't hesitate to get in touch if you think that's the case.


Currently available Webhooks

We currently support webhooks on a number of events related to a subscriber list, which are detailed below. We provide the ability to manage subscriber list webhooks using our lists API. The API allows you to create, test, activate, de-activate, and delete webhooks, as well as allowing you to get all webhooks you've created for a list.

The data format of the payload we'll send as the body of the request is always determined by the payload format you specified when creating the webhook (json or xml).

List Subscribe

When someone subscribes to one of your lists, we'll submit an HTTP POST request similar to the following, to any URLs you've registered with the "Subscribe" event.

The "Subscribe" event is triggered in the following ways:

  1. When subscribers are manually entered on the "Add Subscribers" page
  2. When subscribers are imported from file
  3. When subscribers are moved from an inactive state to "Active" on the "Manage Subscriber List" or "Edit Subscriber" pages
  4. When subscribers subscribe to your list using a subscribe form
  5. When subscribers are added using the Campaign Monitor API
Request made on list subscribe event: JSON XML
POST /subscribe HTTP/1.1
Host: example.com:80
Accept: */*
Content-Type: application/json

{
    "Events": [
        {
            "CustomFields": [
                {
                    "Key": "website", 
                    "Value": "http:\/\/example.org"
                }
            ],
            "Date": "2010-12-14 11:32:00",
            "EmailAddress": "test@example.org",
            "Name": "Test Subscriber",
            "SignupIPAddress": "53.78.123.243",
            "Type": "Subscribe"
        }
    ],
    "ListID": "96c0bbdaa54760c8d9e62a2b7ffa2e13"
}

Subscriber Update

When a subscriber's details are updated, we'll submit an HTTP POST request similar to the following, to any URLs you've registered with the "Update" event.

The "Update" event is triggered in the following ways:

  1. When subscribers have their details updated on the "Edit Subscriber" page
  2. When existing subscribers are re-imported from file
  3. When subscribers update their details from the Preference Center
  4. When existing subscribers are re-added or updated using the Campaign Monitor API
Request made on subscriber update event: JSON XML
POST /subscribe HTTP/1.1
Host: example.com:80
Accept: */*
Content-Type: application/json

{
    "Events": [
        {
            "CustomFields": [
                {
                    "Key": "website", 
                    "Value": "http:\/\/example.org"
                }
            ],
            "Date": "2010-12-14 11:32:00",
          "OldEmailAddress": "test@example.org",
          "EmailAddress": "test@example.org",
          "Name": "Test Subscriber Renamed",
          "Type": "Update",
          "State": "Active"
        }
    ],
    "ListID": "96c0bbdaa54760c8d9e62a2b7ffa2e13"
}

Subscriber De-activate

When a subscriber in your list is de-activated, we'll submit an HTTP POST request similar to the following, to any URLs you've registered with the "Deactivate" event.

The "Deactivate" event is triggered in the following ways:

  1. When subscribers are moved to an inactive state on the "Manage Subscriber List" or "Edit Subscriber" pages
  2. When subscribers unsubscribe by clicking an unsubscribe link
  3. When subscribers unsubscribe using the Preference Center
  4. When a spam complaint is reported by a subscriber
  5. When a hard bounce occurs for a subscriber
  6. When subscribers are unsubscribed using the Campaign Monitor API
Request made on subscriber update event: JSON XML
POST /deactivate HTTP/1.1
Host: example.com:80
Accept: */*
Content-Type: application/json
 
{
    "Events": [
        {
            "CustomFields": [
                {
                    "Key": "website", 
                    "Value": "http:\/\/example.org"
                }
            ],
            "Date": "2010-12-14 11:32:00",
            "EmailAddress": "test@example.org",
            "Name": "Test Subscriber",
            "Type": "Deactivate",
            "State": "Unsubscribed"
        }
    ],
    "ListID": "96c0bbdaa54760c8d9e62a2b7ffa2e13"
}

Debugging and testing tools

RequestBin

Before you start building your integration, RequestBin is an excellent low-friction tool for inspecting our live webhook data, without a bunch of setup pain.

ngrok

You're working furiously on your webhook integration. But webhooks need public URLs, and this isn't ready for production; you just want to receive calls straight to localhost.

Enter ngrok, a handy utility for setting up tunnels between a server running on localhost and a public URL.

No need to push. Just let ngrok setup a public domain; any traffic will be sent straight through to your local machine. You then create the webhook on that public domain and start handling the webhooks calls locally.

Sign up for free.
Then send campaigns for as little as $9/month

Create an account