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

Adds a subscriber to an existing subscriber list, including custom field data if supplied. If the subscriber (email address) already exists, their name and any custom field values are updated with whatever is passed in.

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".

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 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.

Request:
POST
http://api.createsend.com/api/v3/subscribers/{listid}.{xml|json}
Route Values:
{listid}

The ID of the subscriber list to which the subscriber should be added.

Expected Request Body: JSON XML 
 
                    {
                      "EmailAddress": "subscriber@example.com",
                      "Name": "New Subscriber",
                      "CustomFields": [
                        {
                          "Key": "website",
                          "Value": "http://example.com"
                        },
                        {
                          "Key": "interests",
                          "Value": "magic"
                        },
                        {
                          "Key": "interests",
                          "Value": "romantic walks"
                        }
                      ],
                      "Resubscribe": true
                    }

Response:

Contains the email address of the subscriber who was added.

Expected Response: JSON XML 
 
                    HTTP/1.1 201 Created
                    Content-Type: application/json; charset=utf-8

                    "subscriber@example.com"
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 passed in was invalid.

204: In Suppression List

Email Address 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.

Updating a subscriber

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

Any missing 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"

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.

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

Request:
PUT
http://api.createsend.com/api/v3/subscribers/{listid}.{xml|json}?email={email}
Route Values:
{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 Body: JSON XML 
 
                    {
                      "EmailAddress": "changed_address@example.com",
                      "Name": "Changed Name",
                      "CustomFields": [
                        {
                          "Key": "website",
                          "Value": "http://example.com"
                        },
                        {
                          "Key": "interests",
                          "Value": "magic"
                        },
                        {
                          "Key": "interests",
                          "Value": "dungeons and dragons"
                        },
                        {
                          "Key": "age",
                          "Value": "",
                          "Clear": true
                        }
                      ],
                      "Resubscribe": 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:

1: Invalid email address

Email Address passed in was invalid.

201: Already subscribed

New Email Address is already subscribed to the list. Subscriber not updated.

203: 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.

Importing many subscribers

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 and any custom field values are updated with whatever is passed in.

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"

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.

By default, Autoresponder 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 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.

Request:
POST
http://api.createsend.com/api/v3/subscribers/{listid}/import.{xml|json}
Route Values:
{listid}

The ID of the subscriber list to which the subscribers should be added.

Expected Request Body: JSON XML 
 
                    {
                      "Subscribers": [
                        {
                          "EmailAddress": "subscriber1@example.com",
                          "Name": "New Subscriber One",
                          "CustomFields": [
                            {
                              "Key": "website",
                              "Value": "http://example.com"
                            },
                            {
                              "Key": "interests",
                              "Value": "magic"
                            },
                            {
                              "Key": "interests",
                              "Value": "romantic walks"
                            },
                            {
                              "Key": "age",
                              "Value": "",
                              "Clear": true
                            }
                          ]
                        },
                        {
                          "EmailAddress": "subscriber2@example.com",
                          "Name": "New Subscriber Two",
                        },
                        {
                          "EmailAddress": "subscriber3@example.com",
                          "Name": "New Subscriber Three",
                        }
                      ],
                      "Resubscribe": true,
                      "QueueSubscriptionBasedAutoResponders": false
                    }

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): JSON XML 
 
                    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): JSON XML 
 
                    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

Getting a subscriber's details

Retrieves a subscriber's details including their email address, name, active/inactive state, and any custom field data.

Request:
GET
http://api.createsend.com/api/v3/subscribers/{listid}.{xml|json}?email={email}
Route Values:
{listid}

The ID of the subscriber list to which the subscriber belongs.

{email}

The email address of the subscriber whose details should be retrieved.

Response:

Contains the subscriber's details.

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

                    {
                      "EmailAddress": "subscriber@example.com",
                      "Name": "Subscriber One",
                      "Date": "2010-10-25 10:28:00",
                      "State": "Active",
                      "CustomFields": [
                        {
                          "Key": "website",
                          "Value": "http://example.com"
                        },
                        {
                          "Key": "age",
                          "Value": "24"
                        },
                        {
                          "Key": "subscription date",
                          "Value": "2010-03-09"
                        }
                      ]
                    }
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 passed in was invalid.

203: Subscriber not in list

Email Address passed in does not belong to the list matching the List ID.

Getting a subscriber's history

Retrieves a list of campaigns and or autoresponder emails, in response to which a subscriber has made some trackable action. For each campaign or autoresponder email, all actions are recorded, including the event type, the date and the IP address from which the event occurred.

Request:
GET
http://api.createsend.com/api/v3/subscribers/{listid}/history.{xml|json}?email={email}
Route Values:
{listid}

The ID of the subscriber list to which the subscriber belongs.

{email}

The email address of the subscriber whose history should be retrieved.

Response:

Contains a historical record of all the subscriber's trackable actions.

Expected Response: JSON XML 
                    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": "http://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 passed in was invalid.

203: Subscriber not in list

Email Address passed in does not belong to the list matching the List ID.

Unsubscribing a subscriber

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.

Request:
POST
http://api.createsend.com/api/v3/subscribers/{listid}/unsubscribe.{xml|json}
Route Values:
{listid}

The ID of the subscriber list from which the subscriber should be unsubscribed.

Expected Request Body: JSON XML 
 
                    {
                      "EmailAddress": "subscriber@example.com"
                    }
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:

1: Invalid email address

Email Address passed in was invalid.

203: Already removed/Not in list

Subscriber not in list or has already been removed.

Deleting a subscriber

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.

Request:
DELETE
http://api.createsend.com/api/v3/subscribers/{listid}.{xml|json}?email={email}
Route Values:
{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 (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:

1: Invalid email address

Email Address passed in was invalid.