Our API

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

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.

POST https://api.createsend.com/api/v3.1/lists/{clientid}.{xml|json}
Expected body request: JSON XML
{
    "Title": "Website Subscribers",
    "UnsubscribePage": "http://www.example.com/unsubscribed.html",
    "UnsubscribeSetting": "AllClientLists",
    "ConfirmedOptIn": false,
    "ConfirmationSuccessPage": "http://www.example.com/joined.html"
}
Expected response: JSON XML
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

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.

GET https://api.createsend.com/api/v3.1/lists/{listid}.{xml|json}
Expected response: JSON XML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
 
{
    "ConfirmedOptIn": false,
    "Title": "Website Subscribers",
    "UnsubscribePage": "http://www.example.com/unsubscribed.html",
    "UnsubscribeSetting": "AllClientLists",
    "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
    "ConfirmationSuccessPage": "http://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

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.

listid The ID of the list you want the stats for

GET https://api.createsend.com/api/v3.1/lists/{listid}/stats.{xml|json}
Expected response: JSON XML
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

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.

GET
https://api.createsend.com/api/v3.1/lists/{listid}/customfields.{xml|json}
Expected response: JSON XML
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

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.

GET https://api.createsend.com/api/v3.1/lists/{listid}/segments.{xml|json}
Expected response: JSON XML
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

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.

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

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

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

{
    "Results": [
        {
            "EmailAddress": "subs+7t8787Y@example.com",
            "Name": "Person One",
            "Date": "2010-10-25 10:28:00",
            "State": "Active",
            "CustomFields": [
                {
                    "Key": "[website]",
                    "Value": "http://example.com"
                },
                {
                    "Key": "age",
                    "Value": "24"
                },
                {
                    "Key": "[subscriptiondate]",
                    "Value": "2010-03-09"
                }
            ],
            "ReadsEmailWith": "Gmail"
        },
        {
            "EmailAddress": "subs+7878787y8ggg@example.com",
            "Name": "Person Two",
            "Date": "2010-10-25 12:17:00",
            "State": "Active",
            "CustomFields": [
                {
                    "Key": "[website]",
                    "Value": "http://subdomain.example.com"
                }
            ],
            "ReadsEmailWith": "Gmail"
        },
        {
            "EmailAddress": "subs+7890909i0ggg@example.com",
            "Name": "Person Three",
            "Date": "2010-10-25 12:52:00",
            "State": "Active",
            "CustomFields": [
                {
                    "Key": "[website]",
                    "Value": "http://subdomain.example.com"
                }
            ],
            "ReadsEmailWith": ""
        },
        {
            "EmailAddress": "subs@example.com",
            "Name": "Person Four",
            "Date": "2010-10-27 13:13:00",
            "State": "Active",
            "CustomFields": [],
            "ReadsEmailWith": ""
        },
        {
            "EmailAddress": "joey@example.com",
            "Name": "Person Five",
            "Date": "2010-10-27 13:13:00",
            "State": "Active",
            "CustomFields": [],
            "ReadsEmailWith": "Gmail"
        }
    ],
    "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:

  • 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
  • 5: Invalid Date The date must be provided and in the format YYYY-MM-DD

Unconfirmed subscribers

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.

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

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

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

{
    "Results": [
        {
            "EmailAddress": "subs+7t8787Y@example.com",
            "Name": "Unconfirmed One",
            "Date": "2010-10-25 10:28:00",
            "State": "Unconfirmed",
            "CustomFields": [
                {
                    "Key": "[website]",
                    "Value": "http://example.com"
                }
            ],
            "ReadsEmailWith": ""
        },
        {
            "EmailAddress": "subs+7878787y8ggg@example.com",
            "Name": "Unconfirmed Two",
            "Date": "2010-10-25 12:17:00",
            "State": "Unconfirmed",
            "CustomFields": [
                {
                    "Key": "[website]",
                    "Value": "http://subdomain.example.com"
                }
            ],
            "ReadsEmailWith": ""
        }
    ],
    "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:

  • 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
  • 5: Invalid Date The date must be provided and in the format YYYY-MM-DD

Unsubscribed subscribers

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.

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

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

Expected response: JSON XML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
 
{
    "Results": [
        {
            "EmailAddress": "subscriber@example.com",
            "Name": "Unsub One",
            "Date": "2010-10-25 13:11:00",
            "State": "Unsubscribed",
            "CustomFields": [],
            "ReadsEmailWith": "Gmail"
        },
        {
            "EmailAddress": "subscriberone@example.com",
            "Name": "Subscriber",
            "Date": "2010-10-25 13:04:00",
            "State": "Unsubscribed",
            "CustomFields": [
                {
                    "Key": "[website]",
                    "Value": "http://google.com"
                }
            ],
            "ReadsEmailWith": "Gmail"
        },
        {
            "EmailAddress": "example+1@example.com",
            "Name": "Example One",
            "Date": "2010-10-26 10:56:00",
            "State": "Unsubscribed",
            "CustomFields": [],
            "ReadsEmailWith": ""
        },
        {
            "EmailAddress": "example+2@example.com",
            "Name": "Example Two",
            "Date": "2010-10-26 10:56:00",
            "State": "Unsubscribed",
            "CustomFields": [],
            "ReadsEmailWith": ""
        },
        {
            "EmailAddress": "example+3@example.com",
            "Name": "Example Three",
            "Date": "2010-10-26 10:56:00",
            "State": "Unsubscribed",
            "CustomFields": [],
            "ReadsEmailWith": "Gmail"
        }
    ],
    "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:

  • 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
  • 5: Invalid Date The date must be provided and in the format YYYY-MM-DD

Bounced subscribers

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.

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

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.
orderedirection The direction in which results should be ordered. Default: asc.

Expected response: JSON XML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
 
{
    "Results": [
        {
            "EmailAddress": "bouncedsubscriber@example.com",
            "Name": "Bounced One",
            "Date": "2010-10-25 13:11:00",
            "State": "Bounced",
            "CustomFields": [],
            "ReadsEmailWith": ""
        }
    ],
    "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:

  • 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
  • 5: Invalid Date The date must be provided and in the format YYYY-MM-DD

Deleted subscribers

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.

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

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.
orderedirection The direction in which results should be ordered. Default: asc.

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

{
    "Results": [
        {
            "EmailAddress": "deleted+1@example.com",
            "Name": "Deleted Subscriber",
            "Date": "2010-10-25 13:04:00",
            "State": "Deleted",
            "CustomFields": [
                {
                    "Key": "[website]",
                    "Value": "http://google.com"
                }
            ],
            "ReadsEmailWith": "Gmail"
        },
        {
            "EmailAddress": "deleted+2@example.com",
            "Name": "Example Two",
            "Date": "2010-10-26 10:56:00",
            "State": "Deleted",
            "CustomFields": [],
            "ReadsEmailWith": ""
        }
    ],
    "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:

  • 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
  • 5: Invalid Date The date must be provided and in the format YYYY-MM-DD

Updating a list

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 to true, 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.

PUT https://api.createsend.com/api/v3.1/lists/{listid}.{xml|json}
Expected request body: JSON XML
{
    "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 (both XML and JSON):

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

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.

POST https://api.createsend.com/api/v3.1/lists/{listid}/customfields.{xml|json}
Expected request body: JSON XML
{
    "FieldName": "Newsletter Format",
    "DataType": "MultiSelectOne",
    "Options": [ "HTML", "Text" ],
    "VisibleInPreferenceCenter": true
}
Expected Response: JSON XML
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.

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:

  • 254: Invalid Field Name The FieldName provided was not valid.
  • 255: The Field Key already exists A Custom Field using the Key generated from the 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

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

PUT https://api.createsend.com/api/v3.1/lists/{listid}/customfields/{customfieldkey}.{xml|json}
Expected request body: JSON XML
{
    "FieldName": "Newsletter Format Renamed",
    "VisibleInPreferenceCenter": false
}
Expected Response: JSON XML
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.

Updating custom field options

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.

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

PUT https://api.createsend.com/api/v3.1/lists/{listid}/customfields/{customfieldkey}/options.{xml|json}
Expected request body: JSON XML
{
    "KeepExistingOptions": true,
    "Options": [ "First Option", "Second Option", "Third Option" ]
}

Expected response (both XML and JSON):

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:

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

Deleting a custom field

Deletes a specific custom field from a list.

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.

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

Expected response (both XML and JSON):

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

Deletes a subscriber list from your account.
listid The ID of the list you want to delete.

DELETE https://api.createsend.com/api/v3.1/lists/{listid}.{xml|json}

Expected response (both XML and JSON):

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

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

GET https://api.createsend.com/api/v3.1/lists/{listid}/webhooks.{xml|json}
Expected response: JSON XML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[
    {
        "WebhookID": "ee1b3864e5ca61618q98su98qsu9q",
        "Events": [
            "Subscribe"
        ],
        "Url": "http://example.com/subscribe",
        "Status": "Active",
        "PayloadFormat": "Json"
    },
    {
        "WebhookID": "89d8quw98du9qw8ud9q8wud8u98u8",
        "Events": [
            "Deactivate"
        ],
        "Url": "http://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

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.

POST https://api.createsend.com/api/v3.1/lists/{listid}/webhooks.{xml|json}
Expected request body: JSON XML
{
    "Events": [ "Subscribe" ],
    "Url": "http://example.com/subscribe",
    "PayloadFormat": "json"
}
Expected response: JSON XML
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
 
"982u981u298u298u2e9u289e"

Expected response (both XML and JSON):

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:

  • 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

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.

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

Expected response (both XML and JSON):

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.
Webhook request failure example response: JSON XML
{
    "ResultData": {
        "FailureStatus": "ProtocolError",
        "FailureResponseMessage": "NotFound",
        "FailureResponseCode": 404,
        "FailureResponse": ""
    },
    "Code": 610,
    "Message": "The webhook request has failed"
}

Deleting a webhook

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.

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

Expected response (both XML and JSON):

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

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.

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

Expected response (both XML and JSON):

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

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.

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

Expected response (both XML and JSON):

HTTP/1.1 200 OK
Error responses:
Please see our response status codes documentation for details of potential error responses for any API request.

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

Create an account