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.

You're currently veiwing the docs for version 3.2, which is no longer the most up to date API version. Click here for the most up-to-date docs.

Lists

Covers all your list management needs. From creating lists and managing custom fields to accessing active subscribers, anyone who has unsubscribed from the list and more.

Creating a list

Post https://api.createsend.com/api/v3.2/lists/{clientid}.{xml|json}

Creates a new list into which subscribers can be added or imported. Set the list title, landing pages, confirmation setting, and unsubscribe setting. Unsubscribe setting must be either AllClientLists or OnlyThisList. If unsubscribe setting is set to AllClientLists, when someone unsubscribes from this list they will also be unsubscribed from all the client’s lists (recommended). If unsubscribe setting is set to OnlyThisList, when someone unsubscribes from this list they will only be unsubscribed from this list.

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

{
    "Title": "Website Subscribers",
    "UnsubscribePage": "http://www.example.com/unsubscribed.html",
    "UnsubscribeSetting": "AllClientLists",
    "ConfirmedOptIn": false,
    "ConfirmationSuccessPage": "http://www.example.com/joined.html"
}
Expected response: JSONXML
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

"a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1"
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:

  • 250: Duplicate list title Cannot create a list with the same title as another.
  • 251: List Title Empty The list title cannot be empty.
  • 261: Invalid List Unsubscribe Setting Invalid unsubscribe setting. Unsubscribe setting must be either AllClientLists or OnlyThisList.

List details

Get https://api.createsend.com/api/v3.2/lists/{listid}.{xml|json}

A basic summary for each list in your account including the name, ID, type of list (single or confirmed opt-in), any custom unsubscribe and confirmation URLs you’ve specified, as well as the list’s unsubscribe setting.

  • listId The ID of the list you want the details for.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "ConfirmedOptIn": false,
    "Title": "Website Subscribers",
    "UnsubscribePage": "https://www.example.com/unsubscribed.html",
    "UnsubscribeSetting": "AllClientLists",
    "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
    "ConfirmationSuccessPage": "https://www.example.com/joined.html"
}
Error responses:

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

List stats

Get https://api.createsend.com/api/v3.2/lists/{listid}/stats.{xml|json}

Comprehensive summary statistics for each list in your account including subscriber counts across active, unsubscribed, deleted and bounced as well as time-based data like new subscribers today, yesterday, this week, month and year. Here is how we calculate those times:

  • Today since midnight (00:00) in the Client’s TimeZone
  • Yesterday 24 hours starting from midnight of the previous day
  • This Week since midnight on the most recent Sunday
  • This Month since midnight on the 1st of the current month
  • This Year since midnight on January 1st of the current year
  • listid The ID of the list you want the stats for
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "TotalActiveSubscribers": 6,
    "NewActiveSubscribersToday": 0,
    "NewActiveSubscribersYesterday": 8,
    "NewActiveSubscribersThisWeek": 8,
    "NewActiveSubscribersThisMonth": 8,
    "NewActiveSubscribersThisYear": 8,
    "TotalUnsubscribes": 2,
    "UnsubscribesToday": 0,
    "UnsubscribesYesterday": 2,
    "UnsubscribesThisWeek": 2,
    "UnsubscribesThisMonth": 2,
    "UnsubscribesThisYear": 2,
    "TotalDeleted": 0,
    "DeletedToday": 0,
    "DeletedYesterday": 0,
    "DeletedThisWeek": 0,
    "DeletedThisMonth": 0,
    "DeletedThisYear": 0,
    "TotalBounces": 0,
    "BouncesToday": 0,
    "BouncesYesterday": 0,
    "BouncesThisWeek": 0,
    "BouncesThisMonth": 0,
    "BouncesThisYear": 0
}
Error responses:

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

List custom fields

Get https://api.createsend.com/api/v3.2/lists/{listid}/customfields.{xml|json}

Returns all the custom fields for a given list in your account, including the type of field, any additional field options you’ve specified, as well as whether the field is visible in the subscriber preference center.

  • listid The ID of the list you want the custom fields for.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "FieldName": "website",
        "Key": "[website]",
        "DataType": "Text",
        "FieldOptions": [],
        "VisibleInPreferenceCenter": true
    },
    {
        "FieldName": "age",
        "Key": "[age]",
        "DataType": "Number",
        "FieldOptions": [],
        "VisibleInPreferenceCenter": true
    },
    {
        "FieldName": "subscription date",
        "Key": "[subscriptiondate]",
        "DataType": "Date",
        "FieldOptions": [],
        "VisibleInPreferenceCenter": false
    },
    {
        "FieldName": "newsletterformat",
        "Key": "[newsletterformat]",
        "DataType": "MultiSelectOne",
        "FieldOptions": [
            "HTML",
            "Text"
        ],
        "VisibleInPreferenceCenter": true
    }
]
Error responses:

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

List segments

Get https://api.createsend.com/api/v3.2/lists/{listid}/segments.{xml|json}

Returns all the segments you have created for this list including the name, segment and list ID. You can also create your own segments and manage your own segment rules via the API.

  • listid The ID of the list you want the segments for.
Expected response: JSONXML
HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8

    [
      {
        "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
        "SegmentID": "b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1",
        "Title": "Segment One"
      },
      {
        "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
        "SegmentID": "c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1",
        "Title": "Segment Two"
      }
    ]
]]>
Error responses:

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

Active subscribers

Get https://api.createsend.com/api/v3.2/lists/{listid}/active.{xml|json}?date={YYYY-MM-DD}&page={pagenumber}&pagesize={pagesize}&orderfield={email|name|date}&orderdirection={asc|desc}&includetrackingpreference={true|false}

Contains a paged result representing all the active subscribers for a given list. This includes their email address, name, date subscribed (in the client’s timezone), and any custom field data. You have complete control over how results should be returned including page sizes, sort order and sort direction.

  • listid The ID of the list you want the active subscribers for.
  • date Subscribers which became active after the Date value specified will be returned. Must be in the format YYYY-MM-DD. If not provided, results will not be filtered by date.
  • page The results page to retrieve. Default: 1
  • pagesize The number of records to retrieve per results page. Default: 1000
  • orderfield The field which should be used to order the results. Default: date
  • orderdirection The direction in which results should be ordered. Default: asc
  • includetrackingpreference Include subscriber consent to track values. Default: false.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Results": [
        {
            "EmailAddress": "[email protected]",
            "Name": "Person One",
            "Date": "2010-10-25 10:28:00",
            "State": "Active",
            "CustomFields": [
                {
                    "Key": "[website]",
                    "Value": "https://example.com"
                },
                {
                    "Key": "age",
                    "Value": "24"
                },
                {
                    "Key": "[subscriptiondate]",
                    "Value": "2010-03-09"
                }
            ],
            "ReadsEmailWith": "Gmail",
            "ConsentToTrack": "Yes"
        },
        {
            "EmailAddress": "[email protected]",
            "Name": "Person Two",
            "Date": "2010-10-25 12:17:00",
            "State": "Active",
            "CustomFields": [
                {
                    "Key": "[website]",
                    "Value": "https://subdomain.example.com"
                }
            ],
            "ReadsEmailWith": "Gmail",
            "ConsentToTrack": ""
        },
        {
            "EmailAddress": "[email protected]",
            "Name": "Person Three",
            "Date": "2010-10-25 12:52:00",
            "State": "Active",
            "CustomFields": [
                {
                    "Key": "[website]",
                    "Value": "https://subdomain.example.com"
                }
            ],
            "ReadsEmailWith": "",
            "ConsentToTrack": "No"
        },
        {
            "EmailAddress": "[email protected]",
            "Name": "Person Four",
            "Date": "2010-10-27 13:13:00",
            "State": "Active",
            "CustomFields": [],
            "ReadsEmailWith": "",
            "ConsentToTrack": "Yes"
        },
        {
            "EmailAddress": "[email protected]",
            "Name": "Person Five",
            "Date": "2010-10-27 13:13:00",
            "State": "Active",
            "CustomFields": [],
            "ReadsEmailWith": "Gmail",
            "ConsentToTrack": "Yes"
        }
    ],
    "ResultsOrderedBy": "email",
    "OrderDirection": "asc",
    "PageNumber": 1,
    "PageSize": 1000,
    "RecordsOnThisPage": 5,
    "TotalNumberOfRecords": 5,
    "NumberOfPages": 1
}
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:

  • 5: Invalid Date The Send Date provided was invalid.
  • 800: Invalid page number The page number you have provided is invalid.
  • 801: Invalid page size The page size must be between 10 and 1000.
  • 802: Invalid order field The order field must be either email, name or date
  • 803: Invalid order direction The order direction must be either asc or desc.

Unconfirmed subscribers

Get https://api.createsend.com/api/v3.2/lists/{listid}/unconfirmed.{xml|json}?date={YYYY-MM-DD}&page={pagenumber}&pagesize={pagesize}&orderfield={email|name|date}&orderdirection={asc|desc}&includetrackingpreference={true|false}

Contains a paged result representing all the unconfirmed subscribers (those who have subscribed to a confirmed-opt-in list, but have not confirmed their subscription) for a given list. This includes their email address, name, date subscribed (in the client’s timezone), and any custom field data. You have complete control over how results should be returned including page sizes, sort order and sort direction.

  • listid The ID of the list you want the unconfirmed subscribers for.
  • date Subscribers who subscribed on or after the Date value specified will be returned. Must be in the format YYYY-MM-DD. If not provided, results will not be filtered by date.
  • page The results page to retrieve. Default: 1
  • pagesize The number of records to retrieve per results page. Default: 1000
  • orderfield The field which should be used to order the results. Default: date
  • orderdirection The direction in which results should be ordered. Default: asc
  • includetrackingpreference Include subscriber consent to track values. Default: false.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Results": [
        {
            "EmailAddress": "[email protected]",
            "Name": "Unconfirmed One",
            "Date": "2010-10-25 10:28:00",
            "State": "Unconfirmed",
            "CustomFields": [
                {
                    "Key": "[website]",
                    "Value": "https://example.com"
                }
            ],
            "ReadsEmailWith": "",
            "ConsentToTrack": "Yes"
        },
        {
            "EmailAddress": "[email protected]",
            "Name": "Unconfirmed Two",
            "Date": "2010-10-25 12:17:00",
            "State": "Unconfirmed",
            "CustomFields": [
                {
                    "Key": "[website]",
                    "Value": "https://subdomain.example.com"
                }
            ],
            "ReadsEmailWith": "",
            "ConsentToTrack": "No"
        }
    ],
    "ResultsOrderedBy": "email",
    "OrderDirection": "asc",
    "PageNumber": 1,
    "PageSize": 1000,
    "RecordsOnThisPage": 2,
    "TotalNumberOfRecords": 2,
    "NumberOfPages": 1
}
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:

  • 5: Invalid Date The Send Date provided was invalid.
  • 800: Invalid page number The page number you have provided is invalid.
  • 801: Invalid page size The page size must be between 10 and 1000.
  • 802: Invalid order field The order field must be either email, name or date
  • 803: Invalid order direction The order direction must be either asc or desc.

Unsubscribed subscribers

Get https://api.createsend.com/api/v3.2/lists/{listid}/unsubscribed.{xml|json}?date={YYYY-MM-DD}&page={pagenumber}&pagesize={pagesize}&orderfield={email|name|date}&orderdirection={asc|desc}&includetrackingpreference={true|false}

Contains a paged result representing all the unsubscribed subscribers for a given list. This includes their email address, name, date unsubscribed (in the client’s timezone), and any custom field data. You have complete control over how results should be returned including page sizes, sort order and sort direction.

  • listid The ID of the list you want the unsubscribed subscribers for.
  • date Subscribers which unsubscribed on or after the Date value specified will be returned. Must be in the format YYYY-MM-DD. If not provided, results will not be filtered by date.
  • page The results page to retrieve. Default: 1
  • pagesize The number of records to retrieve per results page. Default: 1000
  • orderfield The field which should be used to order the results. Default: date
  • orderdirection The direction in which results should be ordered. Default: asc
  • includetrackingpreference Include subscriber consent to track values. Default: false.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Results": [
        {
            "EmailAddress": "[email protected]",
            "Name": "Unsub One",
            "Date": "2010-10-25 13:11:00",
            "State": "Unsubscribed",
            "CustomFields": [],
            "ReadsEmailWith": "Gmail",
            "ConsentToTrack": "Yes"
        },
        {
            "EmailAddress": "[email protected]",
            "Name": "Subscriber",
            "Date": "2010-10-25 13:04:00",
            "State": "Unsubscribed",
            "CustomFields": [
                {
                    "Key": "[website]",
                    "Value": "https://google.com"
                }
            ],
            "ReadsEmailWith": "Gmail",
            "ConsentToTrack": ""
        },
        {
            "EmailAddress": "[email protected]",
            "Name": "Example One",
            "Date": "2010-10-26 10:56:00",
            "State": "Unsubscribed",
            "CustomFields": [],
            "ReadsEmailWith": "",
            "ConsentToTrack": "No"
        },
        {
            "EmailAddress": "[email protected]",
            "Name": "Example Two",
            "Date": "2010-10-26 10:56:00",
            "State": "Unsubscribed",
            "CustomFields": [],
            "ReadsEmailWith": "",
            "ConsentToTrack": ""
        },
        {
            "EmailAddress": "[email protected]",
            "Name": "Example Three",
            "Date": "2010-10-26 10:56:00",
            "State": "Unsubscribed",
            "CustomFields": [],
            "ReadsEmailWith": "Gmail",
            "ConsentToTrack": "Yes"
        }
    ],
    "ResultsOrderedBy": "email",
    "OrderDirection": "asc",
    "PageNumber": 1,
    "PageSize": 1000,
    "RecordsOnThisPage": 5,
    "TotalNumberOfRecords": 5,
    "NumberOfPages": 1
}
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:

  • 5: Invalid Date The Send Date provided was invalid.
  • 800: Invalid page number The page number you have provided is invalid.
  • 801: Invalid page size The page size must be between 10 and 1000.
  • 802: Invalid order field The order field must be either email, name or date
  • 803: Invalid order direction The order direction must be either asc or desc.

Bounced subscribers

Get https://api.createsend.com/api/v3.2/lists/{listid}/bounced.{xml|json}?date={YYYY-MM-DD}&page={pagenumber}&pagesize={pagesize}&orderfield={email|name|date}&orderdirection={asc|desc}&includetrackingpreference={true|false}

Contains a paged result representing all the bounced subscribers for a given list. This includes their email address, name, date bounced (in the client’s timezone), and any custom field data. You have complete control over how results should be returned including page sizes, sort order and sort direction.

  • listid The ID of the list you want the bounced subscribers for.
  • date Subscribers which bounced on or after the Date value specified will be returned. Must be in the format YYYY-MM-DD. If not provided, results will not be filtered by date.
  • page The results page to retrieve. Default: 1.
  • pagesize The number of records to retrieve per results page. Default: 1000.
  • orderfield The field which should be used to order the results. Default: email.
  • orderdirection The direction in which results should be ordered. Default: asc.
  • includetrackingpreference Include subscriber consent to track values. Default: false.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Results": [
        {
            "EmailAddress": "[email protected]",
            "Name": "Bounced One",
            "Date": "2010-10-25 13:11:00",
            "State": "Bounced",
            "CustomFields": [],
            "ReadsEmailWith": "",
            "ConsentToTrack": "No"
        }
    ],
    "ResultsOrderedBy": "email",
    "OrderDirection": "asc",
    "PageNumber": 1,
    "PageSize": 1000,
    "RecordsOnThisPage": 1,
    "TotalNumberOfRecords": 1,
    "NumberOfPages": 1
}
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:

  • 5: Invalid Date The Send Date provided was invalid.
  • 800: Invalid page number The page number you have provided is invalid.
  • 801: Invalid page size The page size must be between 10 and 1000.
  • 802: Invalid order field The order field must be either email, name or date
  • 803: Invalid order direction The order direction must be either asc or desc.

Deleted subscribers

Get https://api.createsend.com/api/v3.2/lists/{listid}/deleted.{xml|json}?date={YYYY-MM-DD}&page={pagenumber}&pagesize={pagesize}&orderfield={email|name|date}&orderdirection={asc|desc}&includetrackingpreference={true|false}

Contains a paged result representing all the deleted subscribers for a given list. This includes their email address, name, date deleted (in the client’s timezone) and any custom field data. You have complete control over how results should be returned including page sizes, sort order and sort direction.

  • listid The ID of the list you want the deleted subscribers for.
  • date Subscribers which were deleted on or after the Date value specified will be returned. Must be in the format YYYY-MM-DD. If not provided, results will not be filtered by date.
  • page The results page to retrieve. Default: 1.
  • pagesize The number of records to retrieve per results page. Default: 1000.
  • orderfield The field which should be used to order the results. Default: email.
  • orderdirection The direction in which results should be ordered. Default: asc.
  • includetrackingpreference Include subscriber consent to track values. Default: false.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Results": [
        {
            "EmailAddress": "[email protected]",
            "Name": "Deleted Subscriber",
            "Date": "2010-10-25 13:04:00",
            "State": "Deleted",
            "CustomFields": [
                {
                    "Key": "[website]",
                    "Value": "https://google.com"
                }
            ],
            "ReadsEmailWith": "Gmail",
            "ConsentToTrack": "Yes"
        },
        {
            "EmailAddress": "[email protected]",
            "Name": "Example Two",
            "Date": "2010-10-26 10:56:00",
            "State": "Deleted",
            "CustomFields": [],
            "ReadsEmailWith": "",
            "ConsentToTrack": "No"
        }
    ],
    "ResultsOrderedBy": "email",
    "OrderDirection": "asc",
    "PageNumber": 1,
    "PageSize": 1000,
    "RecordsOnThisPage": 2,
    "TotalNumberOfRecords": 2,
    "NumberOfPages": 1
}
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:

  • 5: Invalid Date The Send Date provided was invalid.
  • 800: Invalid page number The page number you have provided is invalid.
  • 801: Invalid page size The page size must be between 10 and 1000.
  • 802: Invalid order field The order field must be either email, name or date
  • 803: Invalid order direction The order direction must be either asc or desc.

Updating a list

Put https://api.createsend.com/api/v3.2/lists/{listid}.{xml|json}

Update the basic settings for any list in your account including the name, type, any subscribe and unsubscribe confirmation pages, as well as the unsubscribe setting.

UnsubscribeSetting must be either AllClientLists or OnlyThisList. If set to AllClientLists, when someone unsubscribes from this list they will also be unsubscribed from all the client’s lists (recommended). If set to OnlyThisList, when someone unsubscribes from this list they will only be unsubscribed from this list. Setting OnlyThisList will result in this list not using the suppression list, meaning that if a subscriber on this list is added to the suppression list they will not be unsubscribed from this list.

If you are updating a list using an UnsubscribeSetting of AllClientLists, you should also specify AddUnsubscribesToSuppList and ScrubActiveWithSuppList. If AddUnsubscribesToSuppList is set totrue, anyone who previously unsubscribed from this list will be added to the suppression list. If ScrubActiveWithSuppList is set to true, this will scrub all of the active subscribers in this list against the suppression list.

  • listid The ID of the list you want to update.
Expected request: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Title": "Website Subscribers",
    "UnsubscribePage": "http://www.example.com/unsubscribed.html",
    "UnsubscribeSetting": "AllClientLists",
    "ConfirmedOptIn": false,
    "ConfirmationSuccessPage": "http://www.example.com/joined.html",
    "AddUnsubscribesToSuppList": true,
    "ScrubActiveWithSuppList": true
}
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:

  • 250: Duplicate list title Cannot create a list with the same title as another.
  • 251: List Title Empty The list title cannot be empty.
  • 261: Invalid List Unsubscribe Setting Invalid unsubscribe setting. Unsubscribe setting must be either AllClientLists or OnlyThisList.

Creating a custom field

Post https://api.createsend.com/api/v3.2/lists/{listid}/customfields.{xml|json}

Creates a new custom field for the provided list into which subscriber data can be added. Set the Custom Field name (from which the Key will be generated), Data Type, and whether the field should be visible in the subscriber preference center.

Available Data Types are Text, Number, MultiSelectOne, MultiSelectMany, Date, Country and USState. For Multi-Valued fields (MultiSelectOne and MultiSelectMany) the possible options must also be provided. In the case of Country and USState fields, the options will be automatically generated and made available when getting the list’s custom fields.

  • listid The ID of the list you want to create the custom field on.
Expected request: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "FieldName": "Newsletter Format",
    "DataType": "MultiSelectOne",
    "Options": [ "HTML", "Text" ],
    "VisibleInPreferenceCenter": true
}
Expected response: JSONXML
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

"[NewsletterFormat]"
Error responses:

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

  • 254: Invalid Field Name The FieldName provided was not valid.
  • 255: The Field Name already exists in this list A Custom Field with the same Field Name already exists.
  • 256: Options defined for Text or Number Field The Options property was neither null or empty for a Text, Number, Date, Country or USState based field
  • 257: No options defined for Multi-Valued field There were no options defined for a Multi-Valued Custom Field (i.e MultiSelectOne or MultiSelectMany)
  • 259: Data type is incorrect The provided Data Type was not one of the following valid options: Text, Number, MultiSelectOne, MultiSelectMany, Country, USState, Date.

Updating a custom field

Put https://api.createsend.com/api/v3.2/lists/{listid}/customfields/{customfieldkey}.{xml|json}

Allows you to update a custom field’s name, as well as whether the field should be visible in the subscriber preference center. It is important to note that if you change the name of a custom field, the custom field key will also be changed. The new key will be returned in the response.

  • listid The ID of the list to which the custom field belongs.
  • customfieldkey The key of the custom field you want to update. This key is provided for each field returned when getting list custom fields
Expected request: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "FieldName": "Newsletter Format Renamed",
    "VisibleInPreferenceCenter": false
}
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

"[NewsletterFormatRenamed]"
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:

  • 253: Invalid Key. Keys must be surrounded with [ ] The provided field key was either not valid or a field with that key does not exist.
  • 254: Invalid Field Name The FieldName provided was not valid.
  • 255: The Field Name already exists in this list A Custom Field with the same Field Name already exists.

Updating custom field options

Put https://api.createsend.com/api/v3.2/lists/{listid}/customfields/{customfieldkey}/options.{xml|json}

Updates the available options for an existing Multi-Valued custom field (MultiSelectOne or MultiSelectMany). Existing options may be maintained or discarded based on the value of the KeepExistingOptions property. This will also remove any segment rules based on the field.

  • listid The ID of the list for the custom field you want to change the options for.
  • customfieldkey The key of the custom field you want to change the options for. This key is provided for each field returned when getting list custom fields
Expected request: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "KeepExistingOptions": true,
    "Options": [ "First Option", "Second Option", "Third Option" ]
}
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:

  • 253: Invalid Key. Keys must be surrounded with [ ] The provided field key was either not valid or a field with that key does not exist.
  • 257: No options defined for Multi-Valued field There were no options defined for a Multi-Valued Custom Field (i.e MultiSelectOne or MultiSelectMany)

Deleting a custom field

Delete https://api.createsend.com/api/v3.2/lists/{listid}/customfields/{customfieldkey}.{xml|json}

Deletes a specific custom field from a list. This will also remove any segment rules based on the field.

  • listid The ID of the list for the custom field you want to delete.
  • customfieldkey The key of the custom field you want to delete. This key is provided for each field returned when getting list custom fields.
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:

  • 253: Invalid Key. Keys must be surrounded with [ ] The provided field key was either not valid or a field with that key does not exist.

Deleting a list

Delete https://api.createsend.com/api/v3.2/lists/{listid}.{xml|json}

Deletes a subscriber list from your account.

  • listid The ID of the list you want to delete.
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:

  • 252: Cannot delete a list attached to at least one campaign draft The specified list is being used by a draft campaign.

List webhooks

Get https://api.createsend.com/api/v3.2/lists/{listid}/webhooks.{xml|json}

Returns all the webhooks you have created for this list. For each webhook, the response includes its ID, URL, status, payload format and the events on which the webhook will be invoked.

  • listid The ID of the subscriber list for which webhooks should be retrieved
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[
    {
        "WebhookID": "ee1b3864e5ca61618q98su98qsu9q",
        "Events": [
            "Subscribe"
        ],
        "Url": "https://example.com/subscribe",
        "Status": "Active",
        "PayloadFormat": "Json"
    },
    {
        "WebhookID": "89d8quw98du9qw8ud9q8wud8u98u8",
        "Events": [
            "Deactivate"
        ],
        "Url": "https://example.com/deactivate",
        "Status": "Active",
        "PayloadFormat": "Json"
    }
]
]]>
Error responses:

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

Creating a webhook

Post https://api.createsend.com/api/v3.2/lists/{listid}/webhooks.{xml|json}

Creates a new webhook for the provided list. Valid events are Subscribe, Deactivate, and Update. Valid payload formats are json, and xml.

  • listid The ID of the list for which the webhook should be created.
Expected request: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Events": [ "Subscribe" ],
    "Url": "http://example.com/subscribe",
    "PayloadFormat": "json"
}
Expected response: JSONXML
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

"982u981u298u298u2e9u289e"
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:

  • 601: Invalid Webhook URL The URL provided for the webhook is invalid
  • 602: Invalid Webhook Format The payload format provided for the webhook is invalid. Supported formats are json and xml.
  • 603: Invalid Webhook Event At least one of the webhook events you have provided are invalid. Valid events are Subscribe, Deactivate, and Update.

Testing a webhook

Get https://api.createsend.com/api/v3.2/lists/{listid}/webhooks/{webhookid}/test.{xml|json}

Attempts to post a webhook payload to the endpoint specified for that webhook. If multiple events are subscribed to for that webhook, the payload will contain an example for each event as part of a batch response. Valid payload formats are json, and xml.

  • listid The ID of the list to which the webhook belongs.
  • webhookid The ID of the webhook for which the test should be sent.
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:

  • 610: The webhook request has failed The attempt to post the webhook request to the provided URL has failed. Check the ResultData object for more detail.

Deleting a webhook

Delete https://api.createsend.com/api/v3.2/lists/{listid}/webhooks/{webhookid}.{xml|json}

Deletes a specific webhook associated with a list.

  • listid The ID of the list from which the webhook should be deleted.
  • webhookid The ID of the webhook you want to delete. This ID is provided for each webhook returned when getting list webhooks.
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.

Activating a webhook

Put https://api.createsend.com/api/v3.2/lists/{listid}/webhooks/{webhookid}/activate.{xml|json}

Activate a webhook associated with a list. Note that despite the fact that this is a PUT request, the body of the request should just be empty.

  • listid The ID of the list with which the webhook you want to activate is associated.
  • webhookid The ID of the webhook to be activated.
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.

Deactivating a webhook

Put https://api.createsend.com/api/v3.2/lists/{listid}/webhooks/{webhookid}/deactivate.{xml|json}

Deactivate a webhook associated with a list. Note that despite the fact that this is a PUT request, the body of the request should just be empty.

  • listid The ID of the list with which the webhook you want to deactivate is associated.
  • webhookid The ID of the webhook to be deactivated.
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.