Our API

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.

When specifying a value for a date custom field, avoid the ambiguous date formats dd/mm/yyyy and mm/dd/yyyy. Instead use an explicit format like yyyy/mm/dd.

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

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.

By default, resubscribed subscribers will not restart any subscription-based autoresponder sequences, 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.

POST https://api.createsend.com/api/v3.1/subscribers/{listid}.{xml|json}
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,
    "RestartSubscriptionBasedAutoresponders": 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.

When specifying a value for a date custom field, avoid the ambiguous date formats dd/mm/yyyy and mm/dd/yyyy. Instead use an explicit format like yyyy/mm/dd.

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

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.

By default, resubscribed subscribers will not restart any subscription-based autoresponder sequences, 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.

PUT https://api.createsend.com/api/v3.1/subscribers/{listid}.{xml|json}?email={email}
Expected body request: 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,
    "RestartSubscriptionBasedAutoresponders": 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.

When specifying a value for a date custom field, avoid the ambiguous date formats dd/mm/yyyy and mm/dd/yyyy. Instead use an explicit format like yyyy/mm/dd.

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"

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.

By default, resubscribed subscribers will not restart any subscription-based autoresponder sequences, 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 subscribers should be added.

POST https://api.createsend.com/api/v3.1/subscribers/{listid}/import.{xml|json}
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,
    "RestartSubscriptionBasedAutoresponders": true
}

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 No subscribers were provided in this batch.

Getting a subscribers's details

Retrieves a subscriber's details including their email address, name, active/inactive state, 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.

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

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"
        }
    ],
    "ReadsEmailWith": "Gmail"
}
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 historical record of campaigns and autoresponder emails received by a subscriber. For each campaign or autoresponder email, all the subscriber's actions are recorded, including the event type, the date, and the IP address from which the event occurred.

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.

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

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

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.

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

POST https://api.createsend.com/api/v3.1/subscribers/{listid}/unsubscribe.{xml|json}
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: Subscriber not in list Email Address passed in does not belong to the list matching the List ID.

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.

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.

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

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.

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

Create an account