Our API

The Campaign Monitor API opens up a world of possibilities for integrating our platform with your favorite CMS, blog, or other third party software.

Subscribers

Everything you need to work with subscribers in your account. From adding a single subscriber to importing a large list. You can even access the full history of each subscriber including all opens, clicks and more.

Adding a subscriber

Post https://api.createsend.com/api/v3.3/subscribers/{listid}.{xml|json}

This method is built for use in websites and integrations that need to add subscribers on a instance-by-instance basis, and adds a subscriber to an existing subscriber list, including custom field data if supplied. If the subscriber (email address) already exists, their name, mobile number, and any custom field values are updated with whatever is passed in. The subscriber data is then passed into a processing queue in Campaign Monitor to be added. For instantaneous adding or to add subscribers in bulk, please use the Importing Many Subscribers method.

When specifying a value for a date custom field, ensure the date is no earlier than 1900/01/01 and no later than 2076/06/06 or it will be ignored. Ambiguous date formats like dd/mm/yyyy and mm/dd/yyyy should also be avoided, use an explicit format like yyyy/mm/dd instead.

Please note that each custom field value has a data limit of 250 characters.

Existing custom field data is not cleared if new custom field values are not provided. Multi-Valued Select Many custom fields are set by providing multiple Custom Field array items with the same key. Date type custom fields may be cleared by passing in a value of “0000-00-00”.

In order to clear a previously saved value of  MobileNumber, send through an empty field. To leave any saved value unchanged, do not pass through the MobileNumber field at all.

When sending SMS it is the responsibility of the implementer to ensure they send permission-based SMS in accordance with all local laws and regulations. The ConsentToSendSms field indicates whether they have obtained the subscriber’s permission to send SMS communications to the mobile number supplied. If permission is not granted Campaign Monitor will not send SMS to the mobile number.

New subscribers only will be sent the follow-up email as configured in the list settings. If the list has been set as double opt-in, they will be sent the verification email, otherwise they will be sent the confirmation email you have set up for the list being subscribed to.

Please note: If the subscriber is in an inactive state or has previously been unsubscribed or added to the suppression list and you specify the Resubscribe input value as true, they will be re-added to the list. Therefore, this method should be used with caution and only where suitable. If Resubscribe is specified as false, the subscriber will not be re-added to the active list.

By default, resubscribed subscribers will not restart any automated workflows, but they will receive any remaining emails. However, if you specify the RestartSubscriptionBasedAutoresponders input value as true, any sequences will be restarted. RestartSubscriptionBasedAutoresponders only affects resubscribing subscribers, and will default to false if omitted.

  • ListID The ID of the subscriber list to which the subscriber should be added.
Expected request: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "EmailAddress": "[email protected]",
    "Name": "New Subscriber",
    "MobileNumber": "+5012398752",
    "CustomFields": [
        {
            "Key": "website",
            "Value": "http://example.com"
        },
        {
            "Key": "interests",
            "Value": "magic"
        },
        {
            "Key": "interests",
            "Value": "romantic walks"
        }
    ],
    "Resubscribe": true,
    "RestartSubscriptionBasedAutoresponders": true,
    "ConsentToTrack":"Yes",
    "ConsentToSendSms": "Yes"
}
  • ConsentToTrack Whether the subscriber has given permission to have their email opens and clicks tracked. This value applies to all subscribers with the same email address, within the same client. If you pass a value of unchanged for an email address, and that address doesn't currently exist in the client, or has no existing value for ConsentToTrack, it is assumed the subscriber has given consent.
    • Yes Tracking is permitted for this email address
    • No Tracking is not permitted for this email address
    • Unchanged Do not change the current email address tracking preference
  • MobileNumber For use with Campaign Monitor's SMS feature. Numbers should be imported in E.164 format, including the + prefix and country code. The endpoint will remove whitespace and common symbols and separators before attempting to import any mobile numbers as E.164. An empty string will remove any saved value, a missing property will leave any saved value unchanged.
  • CONSENTTOSENDSMS An optional parameter to indicate if Consent has been granted by the subscriber to receive Sms. A mobile number must also be provided to apply consent to. It can also be used to indicate Consent is not granted, or omitted to not indicate either way.
    • Yes Receiving Sms is permitted for the supplied mobile number
    • No Receiving Sms is not permitted for the supplied mobile number
    • Unchanged Same as omitting the parameter all together, no indication of consent

Response
Contains the email address of the subscriber who was added.

Expected response: JSONXML
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

"[email protected]"
Error responses:

Please see our response status codes documentation for details of potential error responses for any API request.

If you receive a 400 Bad Request response for this request, these are the possible errors which may be included in the body of the response:

  • 1: Invalid Email Address Email address is missing or incorrectly formatted.
  • 204: In Suppression List Email Address has existed in the selected list before, and currently exists in suppression list. Subscriber is not added.
  • 205: Is Deleted Email Address exists in deleted list. Subscriber is not added.
  • 206: Is Unsubscribed Email Address exists in unsubscribed list. Subscriber is not added.
  • 207: Is Bounced Email Address exists in bounced list. Subscriber is not added.
  • 208: Is Unconfirmed Email Address exists in unconfirmed list. Subscriber is not added.
  • 214: Please provide a consent to track value
  • 215: Please provide a valid consent to track value
  • 220: Invalid mobile number The MobileNumber provided is not a valid E.164 phone number.
  • 221: Invalid email address and mobile number Email address is missing or incorrectly formatted and the mobile number is not a valid E.164 phone number.

Updating a subscriber

Put https://api.createsend.com/api/v3.3/subscribers/{listid}.{xml|json}?email={email}

Updates any aspect of an existing subscriber, including email address, name, mobile number, and custom field data if supplied.

When specifying a value for a date custom field, ensure the date is no earlier than 1900/01/01 and no later than 2076/06/06 or it will be ignored. Ambiguous date formats like dd/mm/yyyy and mm/dd/yyyy should also be avoided, use an explicit format like yyyy/mm/dd instead.

Please note that each custom field value has a data limit of 250 characters.

For all custom fields besides Multi-Valued Select Many fields, any missing values will remain unchanged. When updating Multi-Valued Select Many custom fields, all options that are selected for that customer need to be passed through each time an update is made. If you do not pass through all the options that you wish to have selected for that customer, all historically selected options will be replaced with what’s included in your most recent call. Multi-Valued Select Many custom fields are set by providing multiple custom field array items with the same key.

To clear the value of a custom field, pass a parameter of Clear with a value of true along with the custom field name/value. To remove a specific Multi-Valued Select Many option, pass the option name in the Value field along with the Clear: true parameter. To clear all values of a Multi-Valued Select Many field, pass an empty Value along with the Clear: true parameter. Alternatively, Date type custom fields may be still cleared by passing in a value of “0000-00-00”.

In order to clear a previously saved value of  MobileNumber, send through an empty field. To leave any saved value unchanged, do not pass through the MobileNumber field at all.

When sending SMS it is the responsibility of the implementer to ensure they send permission-based SMS in accordance with all local laws and regulations. The ConsentToSendSms field indicates whether they have obtained the subscriber’s permission to send SMS communications to the mobile number supplied. If permission is not granted Campaign Monitor will not send SMS to the mobile number.

Note: the email value in the query string is the old email address. Use the EmailAddress property in the request body to change the email address.

The update will apply whether the subscriber is active or inactive, although if the subscriber does not exist, a new one will not be added.

Inactive subscribers will not be resubscribed unless Resubscribe is set to true. Operation of the Resubscribe value and associated welcome and confirmation emails are identical to adding a subscriber, and should therefore be treated with the same caution.

By default, resubscribed subscribers will not restart any automated workflows, but they will receive any remaining emails. However, if you specify the RestartSubscriptionBasedAutoresponders input value as true, any sequences will be restarted. RestartSubscriptionBasedAutoresponders only affects resubscribing subscribers, and will default to false if omitted.

Any registered Update webhooks will be triggered, whether the subscriber is inactive or not.

  • ListId The ID of the subscriber list to which the subscriber should be added.
  • Email The email address of the subscriber whose details will be updated. This is regarded as the 'old' email address.
Expected request: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "EmailAddress": "[email protected]",
    "Name": "New Subscriber",
    "MobileNumber": "+5012398752",
    "CustomFields": [
        {
            "Key": "website",
            "Value": "http://example.com"
        },
        {
            "Key": "interests",
            "Value": "magic"
        },
        {
            "Key": "interests",
            "Value": "romantic walks"
        }
    ],
    "Resubscribe": true,
    "RestartSubscriptionBasedAutoresponders": true,
    "ConsentToTrack":"Yes",
    "ConsentToSendSms": "Yes"
}
  • ConsentToTrack Whether the subscriber has given permission to have their email opens and clicks tracked. This value applies to all subscribers with the same email address, within the same client. If you pass a value of unchanged for an email address, and that address doesn't currently exist in the client, or has no existing value for ConsentToTrack, it is assumed the subscriber has given consent.
    • Yes Tracking is permitted for this email address
    • No Tracking is not permitted for this email address
    • Unchanged Do not change the current email address tracking preference
  • MobileNumber For use with Campaign Monitor's SMS feature. Numbers should be imported in E.164 format, including the + prefix and country code. The endpoint will remove whitespace and common symbols and separators before attempting to import any mobile numbers as E.164. An empty string will remove any saved value, a missing property will leave any saved value unchanged.
  • CONSENTTOSENDSMS An optional parameter to indicate if consent has been granted by the subscriber to receive SMS. Consent to send SMS for a subscriber is only recorded when a mobile number is supplied. It can also be used to indicate consent is not granted. If this parameter is omitted it will leave any existing consent preference unchanged.
    • Yes Consent has been granted to send SMS to the supplied mobile number
    • No Consent has not been granted to send SMS to the supplied mobile number
    • Unchanged Do not change the current Consent to send SMS preference
Expected response: (Same for all languages)
HTTP/1.1 200 OK
Error responses:

Please see our response status codes documentation for details of potential error responses for any API request.

If you receive a 400 Bad Request response for this request, these are the possible errors which may be included in the body of the response:

  • 1: Invalid Email Address Email address is missing or incorrectly formatted.
  • 201: Already subscribed New Email Address is already subscribed to the list. Subscriber not updated.
  • 203: Subscriber Not In List Email Address does not belong to the list. Subscriber not updated.
  • 211: Invalid New Email Address New Email Address was invalid. Subscriber not updated.
  • 214: Please provide a consent to track value
  • 215: Please provide a valid consent to track value
  • 220: Invalid mobile number The MobileNumber provided is not a valid E.164 phone number.
  • 221: Invalid email address and mobile number Email address is missing or incorrectly formatted and the mobile number is not a valid E.164 phone number.

Importing many subscribers

Post https://api.createsend.com/api/v3.3/subscribers/{listid}/import.{xml|json}

Please note: When sending to segments, to ensure they have finished calculating, we recommend waiting approximately one hour after importing subscribers, creating segments, or updating segment rules.

Allows you to add many subscribers to a subscriber list in one API request, including custom field data if supplied. If a subscriber (email address) already exists, their name, mobile number, and any custom field values are updated with whatever is passed in. Subscribers will be added instantaneously. The call will only return back once all subscribers have been added.

When specifying a value for a date custom field, ensure the date is no earlier than 1900/01/01 and no later than 2076/06/06 or it will be ignored. Ambiguous date formats like dd/mm/yyyy and mm/dd/yyyy should also be avoided, use an explicit format like yyyy/mm/dd instead.

Please note that each custom field value has a data limit of 250 characters.

Any missing custom field values will remain unchanged. Multi-Valued Select Many custom fields are set by providing multiple Custom Field array items with the same key.

To clear the value of a custom field, pass a parameter of Clear with a value of true along with the custom field name/value. To remove a specific Multi-Valued Select Many option, pass the option name in the Value field along with the Clear: true parameter. To clear all values of a Multi-Valued Select Many field, pass an empty Value along with the Clear: true parameter. Alternatively, Date type custom fields may be still cleared by passing in a value of “0000-00-00”.

In order to clear a previously saved value of  MobileNumber, send through an empty field. To leave any saved value unchanged, do not pass through the MobileNumber field at all.

When sending SMS it is the responsibility of the implementer to ensure they send permission-based SMS in accordance with all local laws and regulations. The ConsentToSendSms field indicates whether they have obtained the subscriber’s permission to send SMS communications to the mobile number supplied. If permission is not granted Campaign Monitor will not send SMS to the mobile number.

New subscribers only will be sent the follow-up email as configured in the list settings. If the list has been set as double opt-in, they will be sent the verification email, otherwise they will be sent the confirmation email you have set up for the list being subscribed to. Also, any registered Subscribe webhooks will be triggered. If the subscriber is not new, any registered Update webhooks will be triggered.

By default, automated workflow emails that are based on the subscription date will not be sent for subscribers imported with this method. This can be overridden by setting the QueueSubscriptionBasedAutoResponders parameter to true.

Please note: If any subscribers are in an inactive state or have previously been unsubscribed or added to the suppression list and you specify the Resubscribe input value as true, they will be re-added to the active list. Therefore, this method should be used with caution and only where suitable. If Resubscribe is specified as false, subscribers will not be re-added to the active list.

By default, resubscribed subscribers will not restart any automated workflow sequences, but they will receive any remaining emails. However, if you specify theRestartSubscriptionBasedAutoresponders input value as true, any sequences will be restarted.RestartSubscriptionBasedAutoresponders only affects resubscribing subscribers, and will default tofalse if omitted.

  • ListID The ID of the subscriber list to which the subscribers should be added.
Expected request: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Subscribers": [
        {
            "EmailAddress": "[email protected]",
            "Name": "New Subscriber One",
            "MobileNumber": "+8012398752",
            "CustomFields": [
                {
                    "Key": "website",
                    "Value": "http://example.com"
                },
                {
                    "Key": "interests",
                    "Value": "magic"
                },
                {
                    "Key": "interests",
                    "Value": "romantic walks"
                },
                {
                    "Key": "age",
                    "Value": "",
                    "Clear": true
                }
            ],
            "ConsentToTrack": "Yes",
            "ConsentToSendSms": "Yes"
        },
        {
            "EmailAddress": "[email protected]",
            "Name": "New Subscriber Two",
            "MobileNumber": "+80-(123)-98754",
            "ConsentToTrack": "No",
            "ConsentToSendSms": "No"
        },
        {
            "EmailAddress": "[email protected]",
            "Name": "New Subscriber Three",
            "MobileNumber": "+801 239 8755",
            "ConsentToTrack": "Unchanged",
            "ConsentToSendSms": "Unchanged"
        }
    ],
    "Resubscribe": true,
    "QueueSubscriptionBasedAutoResponders": false,
    "RestartSubscriptionBasedAutoresponders": true
}
  • ConsentToTrack Whether the subscriber has given permission to have their email opens and clicks tracked. This value applies to all subscribers with the same email address, within the same client. If you pass a value of unchanged for an email address, and that address doesn't currently exist in the client, or has no existing value for ConsentToTrack, it is assumed the subscriber has given consent.
    • Yes Tracking is permitted for this email address
    • No Tracking is not permitted for this email address
    • Unchanged Do not change the current email address tracking preference
  • MobileNumber For use with Campaign Monitor's SMS feature. Numbers should be imported in E.164 format, including the + prefix and country code. The endpoint will remove whitespace and common symbols and separators before attempting to import any mobile numbers as E.164. An empty string will remove any saved value, a missing property will leave any saved value unchanged.
  • CONSENTTOSENDSMS An optional parameter to indicate if consent has been granted by the subscriber to receive SMS. Consent to send SMS for a subscriber is only recorded when a mobile number is supplied. It can also be used to indicate consent is not granted. If this parameter is omitted it will leave any existing consent preference unchanged.
    • Yes Consent has been granted to send SMS to the supplied mobile number
    • No Consent has not been granted to send SMS to the supplied mobile number
    • Unchanged Do not change the current Consent to send SMS preference

Response

If all subscribers are imported correctly, you should expect to receive a 201 Created response, with the details of the import. If only some subscribers are imported correctly, you should expect to receive a 400 Bad Request response, which will include the details of the import. Both these responses are detailed below.

Expected Response (when all subscribers are imported successfully):JSONXML
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "FailureDetails": [],
    "TotalUniqueEmailsSubmitted": 3,
    "TotalExistingSubscribers": 0,
    "TotalNewSubscribers": 3,
    "DuplicateEmailsInSubmission": []
}
Expected Response (when only some subscribers are imported successfully):JSONXML
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
    "ResultData": {
        "TotalUniqueEmailsSubmitted": 3,
        "TotalExistingSubscribers": 2,
        "TotalNewSubscribers": 0,
        "DuplicateEmailsInSubmission": [],
        "FailureDetails": [
            {
                "EmailAddress": "example+1@example",
                "Code": 1,
                "Message": "Invalid Email Address"
            }
        ]
    },
    "Code": 210,
    "Message": "Subscriber Import had some failures"
}
Error responses:

Please see our response status codes documentation for details of potential error responses for any API request.

If you receive a 400 Bad Request response for this request, these are the possible errors which may be included in the body of the response:

  • 209: Too many subscribers in this batch. You can only add 1000 subscribers in one call When importing many subscribers at once, you may only import up to 1000 subscribers at once. If you need to import more than this number of subscribers, you will need to make additional requests.
  • 210: Subscriber Import had some failures There were some failures when attempting to import some subscribers. You will need to inspect the ResultData property of the result for the full details of these failures.
  • 212: No subscribers were provided in this batch No subscribers were provided in this batch.
  • 214: Please provide a consent to track value
  • 215: Please provide a valid consent to track value
  • 220: Invalid mobile number The MobileNumber provided is not a valid E.164 phone number.
  • 221: Invalid email address and mobile number Email address is missing or incorrectly formatted and the mobile number is not a valid E.164 phone number.

Getting a subscriber’s history

Get https://api.createsend.com/api/v3.3/subscribers/{listid}/history.{xml|json}?email={email}

Retrieves a historical record of campaigns and automated workflow emails received by a subscriber. For each campaign or automated workflow email, all the subscriber’s actions are recorded, including the event type, the date, and the IP address from which the event occurred.

Please note: the subscriber history is capped at a maximum of 60 opens/clicks per campaign.

  • ListID The ID of the subscriber list to which the subscriber belongs.
  • Email The email address of the subscriber for which history should be retrieved.

Response
Contains a historical record of all the campaigns and automated workflow emails received by a subscriber.

Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "ID": "fc0ce7105baeaf97f47c99be31d02a91",
        "Type": "Campaign",
        "Name": "Campaign One",
        "Actions": [
            {
                "Event": "Open",
                "Date": "2010-10-12 13:18:00",
                "IPAddress": "192.168.126.87",
                "Detail": ""
            },
            {
                "Event": "Click",
                "Date": "2010-10-12 13:16:00",
                "IPAddress": "192.168.126.87",
                "Detail": "https://example.com/post/12323/"
            }
        ]
    }
]
Error responses:

Please see our response status codes documentation for details of potential error responses for any API request.

If you receive a 400 Bad Request response for this request, these are the possible errors which may be included in the body of the response:

  • 1: Invalid Email Address Email address is missing or incorrectly formatted.
  • 203: Subscriber Not In List Email Address does not belong to the list. Subscriber not updated.

Unsubscribing a subscriber

Post https://api.createsend.com/api/v3.3/subscribers/{listid}/unsubscribe.{xml|json}

Changes the status of an Active Subscriber to an Unsubscribed Subscriber who will no longer receive campaigns sent to the subscriber list to which they belong.

If the list is set to add unsubscribing subscribers to the suppression list, then the subscriber’s email address will also be added to the suppression list.

  • ListID The ID of the subscriber list from which the subscriber should be unsubscribed.
Expected request: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "EmailAddress": "[email protected]"
}
Expected response: (Same for all languages)
HTTP/1.1 200 OK
Error responses:

Please see our response status codes documentation for details of potential error responses for any API request.

If you receive a 400 Bad Request response for this request, these are the possible errors which may be included in the body of the response:

  • 1: Invalid Email Address Email address is missing or incorrectly formatted.
  • 203: Subscriber Not In List Email Address does not belong to the list. Subscriber not updated.

Deleting a subscriber

Delete https://api.createsend.com/api/v3.3/subscribers/{listid}.{xml|json}?email={email}

Changes the status of an Active Subscriber to a Deleted Subscriber who will no longer receive campaigns sent to the subscriber list to which they belong.

This will not result in the subscriber’s email address being added to the suppression list.

  • ListID The ID of the subscriber list from which the subscriber should be deleted.
  • Email The email address of the subscriber who will be deleted from the list.
Expected response: (Same for all languages)
HTTP/1.1 200 OK
Error responses:

Please see our response status codes documentation for details of potential error responses for any API request.

If you receive a 400 Bad Request response for this request, these are the possible errors which may be included in the body of the response:

  • 1: Invalid Email Address Email address is missing or incorrectly formatted.

Getting a subscriber’s details

Get https://api.createsend.com/api/v3.3/subscribers/{listid}.{xml|json}?email={email}&includetrackingpreference={true|false}

Retrieves a subscriber’s details including their email address, name, mobile number, active/inactive state, the date of that last state, the date they initially joined the list, SMS consent, and any custom field data.

  • ListID The ID of the subscriber list to which the subscriber belongs.
  • Email The email address of the subscriber whose details should be retrieved.
  • IncludeTrackingPreference Include subscriber consent to track value. Default: false.

Response
Contains the subscriber’s details. The available states for subscribers are: Active, Unconfirmed, Unsubscribed, Bounced and Deleted.

Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "EmailAddress": "[email protected]",
    "Name": "Subscriber One",
    "MobileNumber": "+5012398752",
    "ListJoinedDate": "2021-10-25 10:28:00",
    "Date": "2021-10-25 10:28:00",
    "State": "Active",
    "CustomFields": [
        {
            "Key": "website",
            "Value": "https://example.com"
        },
        {
            "Key": "age",
            "Value": "24"
        },
        {
            "Key": "subscription date",
            "Value": "2021-03-09"
        }
    ],
    "ReadsEmailWith": "Gmail",
    "ConsentToTrack": "Yes",
    "ConsentToSendSms":"Yes"
}
Error responses:

Please see our response status codes documentation for details of potential error responses for any API request.

If you receive a 400 Bad Request response for this request, these are the possible errors which may be included in the body of the response:

  • 1: Invalid Email Address Email address is missing or incorrectly formatted.
  • 203: Subscriber Not In List Email Address does not belong to the list. Subscriber not updated.