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.

Clients

Contains all the functionality you need to manage the clients in your account. From adding new clients, updating their billing settings, giving them access to their account and accessing their lists, templates and campaigns.

Creating a client

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

Creates a new client in your account with basic contact information and no access to the application. Client billing options are set once the client is created.

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

{
    "CompanyName": "My Company",
    "Country": "Australia",
    "TimeZone": "(GMT+10:00) Canberra, Melbourne, Sydney"
}
Expected response: JSONXML
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

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

  • 152: Invalid Timezone Timezone string is not in the correct format. See here for accessing a list of all timezones.
  • 154: Empty Company Name Company name cannot be empty
  • 157: Invalid Country Country string is either empty or invalid
  • 172: Client Creation Limit You can create a maximum of five (5) clients per thirty (30) minutes

Getting a client’s details

Get https://api.createsend.com/api/v3.3/clients/{clientid}.{xml|json}

Get the complete details for a client including their API key, access level, contact details and billing settings.

If there is only one Person in this Client, their Email Address, Contact Name and Access Details are returned. If there are multiple Persons in this Client, or no Persons at all, these fields are omitted in the response.

MonthlyScheme is included in the JSON payload if the client is on a monthly plan – note this will always return the plan names of Basic, Unlimited and Premier i.e. for the Basic or Lite plans it returns Basic, and for the Unlimited or Essentials plans it returns Unlimited.

  • clientid The ID of the client to be retrieved.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "ApiKey": "639d8cc27198202f5fe6037a8b17a29a59984b86d3289bc9",
    "BasicDetails": {
        "ClientID": "4a397ccaaa55eb4e6aa1221e1e2d7122",
        "CompanyName": "Client One",
        "Country": "Australia",
        "TimeZone": "(GMT+10:00) Canberra, Melbourne, Sydney",
        "PrimaryContactName": "Sally",
        "PrimaryContactEmail": "[email protected]"
    },
    "BillingDetails": {
        "CanPurchaseCredits": true,
        "Credits": 500,
        "MarkupOnDesignSpamTest": 0,
        "ClientPays": true,
        "BaseRatePerRecipient": 1,
        "MarkupPerRecipient": 0,
        "MarkupOnDelivery": 0,
        "BaseDeliveryRate": 5,
        "Currency": "USD",
        "BaseDesignSpamTestRate": 5
    }
}
Error responses:

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

Getting subscriber lists

Get https://api.createsend.com/api/v3.3/clients/{clientid}/lists.{xml|json}

Returns all the subscriber lists that belong to that client, including the list name and ID.

  • clientid The ID of the client for which subscriber lists should be retrieved.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "ListID": "a58ee1d3039b8bec838e6d1482a8a965",
        "Name": "List One"
    },
    {
        "ListID": "99bc35084a5739127a8ab81eae5bd305",
        "Name": "List Two"
    }
]
Error responses:

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

Getting lists for an email address

Get https://api.createsend.com/api/v3.3/clients/{clientid}/listsforemail.{xml|json}?email={email}

Returns all the subscriber lists across the client, to which an email address is subscribed.

For each list to which the email address is subscribed, you will receive the list ID, list name, the state of the subscriber on the list, and the date the subscriber was added to the list (in the client’s timezone).

  • clientid The ID of the client for which lists should be retrieved.
  • email The email address for which lists should be retrieved.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "ListID": "a58ee1d3039b8bec838e6d1482a8a965",
        "ListName": "List One",
        "SubscriberState": "Active",
        "DateSubscriberAdded": "2010-03-19 11:15:00"
    },
    {
        "ListID": "99bc35084a5739127a8ab81eae5bd305",
        "ListName": "List Two",
        "SubscriberState": "Unsubscribed",
        "DateSubscriberAdded": "2011-04-01 01:27:00"
    }
]
Error responses:

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

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

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

Getting segments

Get https://api.createsend.com/api/v3.3/clients/{clientid}/segments.{xml|json}

Contains a list of all list segments belonging to a particular client.

  • clientid The ID of the client for which segments should be retrieved.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "ListID": "a58ee1d3039b8bec838e6d1482a8a965",
        "SegmentID": "46aa5e01fd43381863d4e42cf277d3a9",
        "Title": "Segment One"
    },
    {
        "ListID": "8dffb94c60c5faa3d40f496f2aa58a8a",
        "SegmentID": "dhw9q8jd9q8wd09quw0d909wid9i09iq",
        "Title": "Segment Two"
    }
]
Error responses:

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

Getting suppression list

Get https://api.createsend.com/api/v3.3/clients/{clientid}/suppressionlist.{xml|json}?page={page}&pagesize={pagesize}&orderfield={email|date}&orderdirection={asc|desc}

Contains a paged result representing the client’s suppression list.

  • clientid The ID of the client for which their suppression list should be retrieved.
  • 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.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Results": [
        {
            "SuppressionReason": "Bounced",
            "EmailAddress": "[email protected]",
            "Date": "2010-10-26 10:55:31",
            "State": "Suppressed"
        },
        {
            "SuppressionReason": "Unsubscribed",
            "EmailAddress": "[email protected]",
            "Date": "2010-10-26 10:55:31",
            "State": "Suppressed"
        },
        {
            "SuppressionReason": "Unsubscribed",
            "EmailAddress": "[email protected]",
            "Date": "2010-10-26 10:55:31",
            "State": "Suppressed"
        },
        {
            "SuppressionReason": "Reason Unavailable",
            "EmailAddress": "[email protected]",
            "Date": "2010-10-25 13:11:04",
            "State": "Suppressed"
        },
        {
            "SuppressionReason": "Reason Unavailable",
            "EmailAddress": "[email protected]",
            "Date": "2010-10-25 13:04:15",
            "State": "Suppressed"
        }
    ],
    "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.

Suppress email addresses

Post https://api.createsend.com/api/v3.3/clients/{clientid}/suppress.{xml|json}

Adds the email addresses provided to the client’s suppression list.

  • clientid The ID of the client whose suppression list will have the provided email addresses added to it.
Expected request: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

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

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

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

Unsuppress an email address

Put https://api.createsend.com/api/v3.3/clients/{clientid}/unsuppress.{xml|json}?email={email}

Unsuppresses an email address by removing the email address from a client’s suppression list.

  • clientid The ID of the client from whose suppression list the email address should be removed.
  • email The email address to be removed from the suppression list.
Expected response: (Same for all languages)
HTTP/1.1 200 OK
Error responses:

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

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

  • 1: Invalid Email Address Email address is missing or incorrectly formatted.
  • 176: Email address not in suppression list The email address provided is not in the client's suppression list.

Getting templates

Get https://api.createsend.com/api/v3.3/clients/{clientid}/templates.{xml|json}

Contains a list of the templates belonging to the client including the ID, name and a URL for a screenshot and HTML preview of the template.

  • clientid The ID of the client for which templates should be retrieved.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "TemplateID": "5cac213cf061dd4e008de5a82b7a3621",
        "Name": "Template One",
        "PreviewURL": "https://preview.createsend.com/templates/publicpreview/01AF532CD8889B33?d=r",
        "ScreenshotURL": "https://preview.createsend.com/ts/r/14/833/263/14833263.jpg?0318092541"
    },
    {
        "TemplateID": "da645c271bc85fb6550acff937c2ab2e",
        "Name": "Template Two",
        "PreviewURL": "https://preview.createsend.com/templates/publicpreview/C8A180629495E798?d=r",
        "ScreenshotURL": "https://preview.createsend.com/ts/r/18/7B3/552/187B3552.jpg?0705043527"
    }
]
Error responses:

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

Setting basic details

Put https://api.createsend.com/api/v3.3/clients/{clientid}/setbasics.{xml|json}

Update the basic account details for an existing client including their name, contact details and time zone.

If a client is set to ClientPays: true, changing the client’s country may have unexpected tax implications. If you need to change a client’s country, do so through the UI by updating their payment details.

  • clientid The ID of the client for which basic details should be set.
Expected request: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "CompanyName": "My Company",
    "Country": "Australia",
    "TimeZone": "(GMT+10:00) Canberra, Melbourne, Sydney"
}
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:

  • 110: Deprecated Method Client details can be updated in this way if there is only one Person in this Client. If there are multiple Persons, or no Persons at all, you cannot set their details this way. Instead, update each Person's details.
  • 152: Invalid Timezone Timezone string is not in the correct format. See here for accessing a list of all timezones.
  • 154: Empty Company Name Company name cannot be empty
  • 157: Invalid Country Country string is either empty or invalid

Setting PAYG billing

Put https://api.createsend.com/api/v3.3/clients/{clientid}/setpaygbilling.{xml|json}

Set if a client can pay for their own campaigns and design and spam tests using our PAYG billing. Set the mark-up percentage on each type of fee, and if the client can purchase their own email credits to access bulk discounts.

Any specific markup values provided for the MarkupOnDelivery, MarkupPerRecipient or MarkupOnDesignSpamTest fields will override the percentage markup for those fields only, these fields are optional and should be omitted when not required. The MarkupOnDelivery and MarkupOnDesignSpamTest fields should be in the major unit for the specified currency (e.g “6.5” means “$6.50”), whilst the MarkupPerRecipient should be in the specified currencies minor unit (e.g “6.5” means “6.5 cents”). Note: Specific values can not be provided for the credit pricing tiers.

Currencies supported are USD (US Dollars), GBP (Great Britain Pounds), EUR (Euros), CAD(Canadian Dollars), AUD (Australian Dollars), and NZD (New Zealand Dollars).

  • clientid The ID of the client for which PAYG billing settings should be set.
Expected request: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Currency": "AUD",
    "CanPurchaseCredits": false,
    "ClientPays": true,
    "MarkupPercentage": 20,
    "MarkupOnDelivery": 5,
    "MarkupPerRecipient": 4,
    "MarkupOnDesignSpamTest": 3
}
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:

  • 167: Invalid Currency Code The currency selected is invalid. Please ensure you use a valid currency.
  • 170: Markup Rate Too Low The Markup Percentage must be greater than or equal to zero
  • 173: Cannot set billing without access You cannot set client billing options for clients without Create Send access

Setting monthly billing

Put https://api.createsend.com/api/v3.3/clients/{clientid}/setmonthlybilling.{xml|json}

Set if a client can pay for their own campaigns and design and spam tests using our monthly billing. Set the currency they should pay in plus mark-up percentage that will apply to the base prices at each pricing tier.

Currencies supported are USD (US Dollars), GBP (Great Britain Pounds), EUR (Euros), CAD (Canadian Dollars), AUD (Australian Dollars), and NZD (New Zealand Dollars).

MonthlyScheme is optional. Supported values are Basic and Unlimited and PremierNote that Lite and Essentials are also supported values for this endpoint, but be aware that Client Details will always return the plan names of Basic, Unlimited and Premier i.e. for Basic or Lite it returns Basic, and for Unlimited or Essentials it returns Unlimited.

  • clientid The ID of the client for which monthly billing settings should be set.
Expected request: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Currency": "AUD",
    "ClientPays": true,
    "MarkupPercentage": 20,
    "MonthlyScheme": "Basic",
}
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:

  • 167: Invalid Currency Code The currency selected is invalid. Please ensure you use a valid currency.
  • 170: Markup Rate Too Low The Markup Percentage must be greater than or equal to zero
  • 173: Cannot set billing without access You cannot set client billing options for clients without Create Send access

Transfer credits

Post https://api.createsend.com/api/v3.3/clients/{clientid}/credits.{xml|json}

Transfer credits from your account to a client, or transfer credits from a client to your account. The Credits field should contain either a positive integer if you wish to allocate credits from your account to a client, or a negative integer if you wish to deduct credits from a client back into your account.

For example, to deduct 200 credits from a client (and transfer those credits back to your account) you would provide a value of -200 for the Credits field. And to allocate 200 credits from your account to a client, you would provide a value of 200 for the Credits field.

If the CanUseMyCreditsWhenTheyRunOut field is set to true, the client will be able to continue sending using your credits or payment details once they run out of credits. If the CanUseMyCreditsWhenTheyRunOut field is set to false, the client will not be able to continue sending until you allocate more credits to them.

  • clientid The ID of the client for which the credit transfer will be made.
Expected request: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Credits": 200,
    "CanUseMyCreditsWhenTheyRunOut": false
}
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "AccountCredits": 800,
    "ClientCredits": 200
}
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:

  • 177: Attempted to transfer greater than total client credits You attempted to transfer more than the total number of credits belonging to the client.
  • 178: Attempted to transfer greater than total account credits You attempted to transfer more than the total number of credits in your account.

Deleting a client

Delete https://api.createsend.com/api/v3.3/clients/{clientid}.{xml|json}

Delete an existing client from your account.

  • clientid The ID of the client to be deleted.
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.

Adding a person

Post https://api.createsend.com/api/v3.3/clients/{clientid}/people.{xml|json}

Adds a new person to the client. You can use the permissions helper below for selecting the appropriate AccessLevel:

Permissions
They can do everything but can't create templates. They can’t manage people themselves.

Access level:

  • clientid The ID of the client to add the person to.
Expected request: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "EmailAddress": "[email protected]",
  "Name": "Sally Sparrow",
  "AccessLevel": 23,
  "Password": "opensesame"
}
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
   "EmailAddress": "[email protected]"
}
Error responses:

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

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

  • 1: Invalid Email Address Email address is missing or incorrectly formatted.
  • 150: Email Taken A person with that email address is already associated with this client.
  • 153: Invalid Access Level Specified access level does not exist. Please check the documentation for valid access level settings.
  • 174: Unsafe Password Supplied password is considered unsafe and easily hackable. Please choose another.
  • 175: Invalid Password If password is supplied, it must be at least 6 characters.
  • 701: Empty Person Name Person name cannot be empty.

Updating a person

Put https://api.createsend.com/api/v3.3/clients/{clientid}/people.{xml|json}?email={email}

Updates any aspect of a person including their email address, name and access level. Note: theemail value in the query string is the old email address. Use the EmailAddress property in the request body to change the email address.

You can use the permissions helper for selecting the appropriate AccessLevel.

Permissions
They can do everything but can't create templates. They can’t manage people themselves.

Access level:

  • clientid The ID of the client with which the person is associated.
  • email The email address of the person whose details will be updated. This is regarded as the 'old' email address.
Expected request: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "EmailAddress": "[email protected]",
  "Name": "Sam Sparrow",
  "AccessLevel": 31,
  "Password": "opensesame"
}
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
   "EmailAddress": "[email protected]"
}
Error responses:

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

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

  • 1: Invalid Email Address Email address is missing or incorrectly formatted.
  • 150: Email Taken A person with that email address is already associated with this client.
  • 153: Invalid Access Level Specified access level does not exist. Please check the documentation for valid access level settings.
  • 174: Unsafe Password Supplied password is considered unsafe and easily hackable. Please choose another.
  • 175: Invalid Password If password is supplied, it must be at least 6 characters.
  • 702: Person not found No person with that email address is associated with this client.
  • 701: Empty Person Name Person name cannot be empty.

Getting people

Get https://api.createsend.com/api/v3.3/clients/{clientid}/people.{xml|json}

Contains a list of all (active or invited) people associated with a particular client. This will not include account administrators.

  • clientid The ID of the client for which the people should be retrieved.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "EmailAddress": "[email protected]",
    "Name": "Sally Sparrow",
    "AccessLevel": 31,
    "Status": "Waiting to Accept the Invitation"
  },
  {
    "EmailAddress": "[email protected]",
    "Name": "John Jones",
    "AccessLevel": 23,
    "Status": "Active"
  }
]
Error responses:

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

Person details

Get https://api.createsend.com/api/v3.3/clients/{clientid}/people.{xml|json}?email={email}

Returns the details of a single person associated with a client.

  • clientid The ID of the client for which the person details should be retrieved.
  • email The email address of the person whose information should be retrieved.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "EmailAddress": "[email protected]",
  "Name": "John Jones",
  "AccessLevel": 23,
  "Status": "Active"
}
Error responses:

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

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

  • 1: Invalid Email Address Email address is missing or incorrectly formatted.
  • 702: Person not found No person with that email address is associated with this client.

Deleting a Person

Delete https://api.createsend.com/api/v3.3/clients/{clientid}/people.{xml|json}?email={email}

Changes the status of an active person to a deleted person. They will no longer be able to log into this client.

  • clientid The ID of the client for which the person details should be deleted.
  • email The email address of the person to be deleted.
Expected response: (Same for all languages)
HTTP/1.1 200 OK
Error responses:

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

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

  • 1: Invalid Email Address Email address is missing or incorrectly formatted.
  • 702: Person not found No person with that email address is associated with this client.
  • 703: Cannot delete last person There must always be at least one person associated with the client.

Setting primary contact

Put https://api.createsend.com/api/v3.3/clients/{clientid}/primarycontact.{xml|json}?email={email}

Sets the primary contact for the client to be the person with the specified email address.

  • clientid The ID of the client for which the primary contact is to be set.
  • email The email address of the person to be assigned as the primary contact for the client.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "EmailAddress": "[email protected]",
}
Error responses:

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

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

  • 1: Invalid Email Address Email address is missing or incorrectly formatted.
  • 702: Person not found No person with that email address is associated with this client.
  • 704: Person not active The specified person has not accepted their invitation yet.

Getting primary contact

Get https://api.createsend.com/api/v3.3/clients/{clientid}/primarycontact.{xml|json}

Returns the email address of the person who is selected as the primary contact for this client.

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

{
  "EmailAddress": "[email protected]",
}
Error responses:

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

Getting tags

Get https://api.createsend.com/api/v3.3/clients/{clientid}/tags.{xml|json}

Returns a list of all campaign tags for a client in ascending order including tag name, and the total number of campaigns for each tag.

  • ClientID The ID of the client for which tags should be retrieved.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "Name": "Monthly promo", 
        "NumberOfCampaigns": "120"
    },
    {        
        "Name": "Marketing tips",
        "NumberOfCampaigns": "62"
    }
]
Error responses:

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

Getting sent campaigns

Get https://api.createsend.com/api/v3.3/clients/{clientid}/campaigns.{xml|json}?sentFromDate={YYYY-MM-DD}&sentToDate={YYYY-MM-DD}&tags={tags}&page={page}&pagesize={pagesize}&orderdirection={asc|desc}

Returns a list of sent campaigns for a client including from name, from email, reply to email, web version URL, ID, subject, name, date sent, the total number of recipients, and the list of attached tags. By default, the list of campaigns will be returned in reverse order of SentDate (most recent first), paginated according to the defined behaviour. You can specify how results are returned including page sizes and sort direction. If tags are specified, this filter will be applied accordingly.

  • ClientID The ID of the client for which sent campaigns should be retrieved.
  • SentFromDate (optional) Campaigns sent on or after this value will be returned. Must be in the format YYYY-MM-DD. If not provided, results will go back to the beginning of the client’s history.
  • SentToDate (optional) Campaigns sent before this value will be returned. Must be in the format YYYY-MM-DD. If not provided, results will include the most recent sent campaigns.
  • Tags (optional) A comma separated list of tags to filter sent campaigns. Sent campaigns with all the tags specified will be returned.
  • Page (optional) The page number of results to get. Default: 1
  • PageSize (optional) The number of records to get on the current page. The value can be between 1 and 1000. Default: 1000.
  • OrderDirection (optional) The direction in which results should be ordered. This sorting can be either ASC or DESC and uses the SentDate column. Default DESC
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Results":[
        {
            "FromName": "My Name",
            "FromEmail": "[email protected]",
            "ReplyTo": "[email protected]",
            "WebVersionURL": "https://createsend.com/t/r-765E86829575EE2C/",
            "WebVersionTextURL": "https://createsend.com/t/r-765E86829575EE2C/t",
            "CampaignID": "fc0ce7105baeaf97f47c99be31d02a91",
            "Subject": "Campaign One",
            "Name": "Campaign One",
            "SentDate": "2020-10-12 12:58:00",
            "TotalRecipients": 2245,
            "Tags": ["2020","COVID-19"],		
        },
        {
            "FromName": "My Name",
            "FromEmail": "[email protected]",
            "ReplyTo": "[email protected]",
            "WebVersionURL": "https://createsend.com/t/r-DD543566A87C9B8B/",
            "WebVersionTextURL": "https://createsend.com/t/r-DD543566A87C9B8B/t",
            "CampaignID": "072472b88c853ae5dedaeaf549a8d607",
            "Subject": "Campaign Two",
            "Name": "Campaign Two",
            "SentDate": "2020-10-06 16:20:00",
            "TotalRecipients": 11222,
            "Tags": ["Charity","COVID-19"],		
        }
    ],
    "ResultsOrderedBy": "SentDate",
    "OrderDirection": "desc",
    "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.
  • 803: Invalid order direction The order direction must be either asc or desc.
  • 920: Invalid from date The date must be provided in the format YYYY-MM-DD
  • 922: Invalid to date The date must be provided in the format YYYY-MM-DD
  • 927: Invalid date range "From Date" must be before "To Date"

Getting scheduled campaigns

Get https://api.createsend.com/api/v3.3/clients/{clientid}/scheduled.{xml|json}

Returns all currently scheduled campaigns for a client including from name, from email, reply to email, preview URL, ID, subject, name, date created, date scheduled, the scheduled timezone and associated tags.

  • ClientID The ID of the client for which scheduled campaigns should be retrieved.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "DateScheduled": "2022-05-25 10:40:00",
        "ScheduledTimeZone": "(GMT+10:00) Canberra, Melbourne, Sydney",
        "CampaignID": "827dbbd2161ea9989fa11ad562c66937",
        "Name": "Magic Issue One",
        "Subject": "Magic Issue One",
        "FromName": "My Name",
        "FromEmail": "[email protected]",
        "ReplyTo": "[email protected]",
        "DateCreated": "2021-05-24 10:37:00",
        "PreviewURL": "https://createsend.com/t/r-DD543521A87C9B8B/",
        "PreviewTextURL": "https://createsend.com/t/r-DD543521A87C9B8B/t",
        "Tags": [
            "morning"
        ]
    },
    {
        "DateScheduled": "2022-05-29 12:20:00",
        "ScheduledTimeZone": "(GMT+10:00) Canberra, Melbourne, Sydney",
        "CampaignID": "4f54bbd2161e65789fa11ad562c66937",
        "Name": "Magic Issue Two",
        "Subject": "Magic Issue Two",
        "FromName": "My Name",
        "FromEmail": "[email protected]",
        "ReplyTo": "[email protected]",
        "DateCreated": "2021-05-24 10:39:00",
        "PreviewURL": "https://createsend.com/t/r-DD913521A87C9B8B/",
        "PreviewTextURL": "https://createsend.com/t/r-DD913521A87C9B8B/t",
        "Tags": []
    }
]
Error responses:

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

Getting draft campaigns

Get https://api.createsend.com/api/v3.3/clients/{clientid}/drafts.{xml|json}

Returns a list of all draft campaigns belonging to that client including from name, from email, reply to email, preview URL, ID, subject, name, the date the draft was created and associated tags.

  • ClientID The ID of the client for which drafts campaigns should be retrieved.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "CampaignID": "7c7424792065d92627139208c8c01db1",
        "Name": "Draft One",
        "Subject": "Draft One",
        "FromName": "My Name",
        "FromEmail": "[email protected]",
        "ReplyTo": "[email protected]",
        "DateCreated": "2021-08-19 16:08:00",
        "PreviewURL": "https://createsend.com/t/r-E97A7BB2E6983DA1/",
        "PreviewTextURL": "https://createsend.com/t/r-E97A7BB2E6983DA1/t",
        "Tags": [
  	    "discount",
            "halloween"
        ]
    },
    {
        "CampaignID": "2e928e982065d92627139208c8c01db1",
        "Name": "Draft Two",
        "Subject": "Draft Two",
        "FromName": "My Name",
        "FromEmail": "[email protected]",
        "ReplyTo": "[email protected]",
        "DateCreated": "2021-08-19 16:08:00",
        "PreviewURL": "https://createsend.com/t/r-E97A7BB2E6983DA1/",
        "PreviewTextURL": "https://createsend.com/t/r-E97A7BB2E6983DA1/t",
        "Tags": [
            "halloween"
        ]
    }
]
Error responses:

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

Getting sending domains

Post https://api.createsend.com/api/v3.3/clients/{clientid}/sendingdomains.{xml|json}?sendingdomain={sendingdomain}&selector={selector}

Retrieve all sending domains and their details for the client. 

  • CLIENTID The ID of the client for which sending domains should be retrieved.
  • SENDINGDOMAIN (optional) The sending domain for which results should be retrieved.
  • SELECTOR (optional) The selector for which results should be retrieved.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "SendingDomain": "example.com", 
        "Selector": "cm",
        "PublicKey": "MIGfMA0GCSqGS.....",
        "DNSRecords": {
                "DKIM": {
                        "Validation": "Verified",
                        "Key": "cm._domainkey.example.com",
                        "Value": "k=rsa; p=MIGfMA0GCSqGS..."
                },
                "DMARC": {
                        "Validation": "Missing Record"
                },
                "SPF": {
                        "Validation": "Verified"
                }
         },
    },
     {
        "SendingDomain": "test.com", 
        "Selector": "cm",
        "PublicKey": "MIGfMA0GCSqGS.....",
        "DNSRecords": {
                "DKIM": {
                        "Validation": "Verified",
                        "Key": "cm._domainkey.test.com",
                        "Value": "k=rsa; p=MIGfMA0GCSqGS..."
                },
                "DMARC": {
                        "Validation": "Verified"
                },
                "SPF": {
                        "Validation": "Verified"
                }
         },
    },
]
Error responses:

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

Adding a sending domain

Post https://api.createsend.com/api/v3.3/clients/{clientid}/sendingdomains.{xml|json}

Add a sending domain. All parameters in the body are optional except the SendingDomain.

If you only specify a SendingDomain in the body of the request then we will generate the keys and default the selector to ‘cm’. 

If you specify the SendingDomain and Selector in the body of the request then we will generate the keys.

Alternatively you can supply all the parameters yourself, SendingDomain, Selector, PrivateKey, and PublicKey.

  • CLIENTID The ID of the client on which to add the sending domain.
Expected request: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "SendingDomain": "example.com",
    "Selector": "myCustomSelector",
    "PublicKey": "MIGfMA0GCSqGS...",
    "PrivateKey": "MIICXQIBAAKBgQ...",
}
Expected response: JSONXML
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
        "SendingDomain": "example.com", 
        "Selector": "myCustomSelector",
        "PublicKey": "MIGfMA0GCSqGS.....",
        "DNSRecords": {
                "DKIM": {
                        "Validation": "Missing Record",
                        "Key": "cm2024._domainkey.example.com",
                        "Value": "k=rsa; p=MIGfMA0GCSqGS..."
                },
                "DMARC": {
                        "Validation": "Verified"
                },
                "SPF": {
                        "Validation": "Verified"
                }
         },
 }
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:

  • 3501 DomainNameNotValid Domain name is missing or invalid
  • 3502 DomainNameIsFreeEmailDomain Domain name is a free email domain which is not valid
  • 3503 DomainNameRegistrationFailure Domain name is not a registered domain
  • 3504 DomainExistsInThisAccount Domain already exists in this account
  • 3505 DomainExistsInAnotherAccount Domain already exists in another account
  • 3506 DomainExistsInThisClient Domain already exists in this client
  • 3507 InvalidSelector Selector is missing or invalid
  • 3508 InvalidPublicKey Public key is missing or invalid
  • 3509 InvalidPrivateKey Private key is missing or invalid. This includes the length not adhering to standards
  • 3512 DomainAndSelectorExistsInAnotherAccount Domain and selector combination already exists in another account
  • 3513 DomainAndSelectorExistsInThisAccount Domain and selector combination already exists in this account
  • 3514 DomainAndSelectorExistsInThisClient Domain and selector combination already exists in this client

Delete a sending domain

Delete https://api.createsend.com/api/v3.3/clients/{clientid}/sendingdomains.{xml|json}?sendingdomain={sendingdomain}&selector={selector}

Delete a sending domain.

  • CLIENTID The ID of the client on which to delete the sending domain.
  • SENDINGDOMAIN The sending domain that will be deleted.
  • SELECTOR The selector of the sending domain that will be deleted.
Expected response:
HTTP/1.1 200 OK
Error responses:

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

  • 3510 DomainSelectorCombinationNotFound Domain name and selector combination could not be found

Copy a sending domain to another client

Post https://api.createsend.com/api/v3.3/clients/{clientid}/sendingdomains/copy.{xml|json}

Copies a sending domain from one client to another. Both clients must reside within the same account. Only verified sending domains can be copied.

  • CLIENTID the source client id from which to copy.
Expected request: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "DestinationClientID": "da694f4852b355",
    "SendingDomain": "example.com",
    "Selector": "cm"
}
Expected response: JSONXML
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
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:

  • 125 InvalidDestinationClientID Destination client ID is missing or invalid
  • 3501 DomainNameNotValid Domain name is missing or invalid
  • 3507 InvalidSelector Selector is missing or invalid
  • 3510 DomainSelectorCombinationNotFound Domain name and selector combination could not be found

Verify sending domains

Put https://api.createsend.com/api/v3.3/clients/{clientid}/sendingdomains/authenticate.{xml|json}?sendingdomain={sendingdomain}&selector={selector}

Verifies and authenticates the DNS records of a sending domain. After creating a sending domain or updating DNS records this endpoint needs to be called to update the state of the sending domain within our system.

  • CLIENTID The ID of the client on which to verify the sending domain.
  • SENDINGDOMAIN The sending domain that will be verified.
  • SELECTOR (optional) The selector of the sending domain that will be verified. If not specified then all matching domains in the client will be verified.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "SendingDomain": "example.com", 
        "Selector": "cm",
        "PublicKey": "MIGfMA0GCSqGS...",
        "DNSRecords": {
                "DKIM": {
                        "Validation": "Verified",
                        "Key": "cm._domainkey.example.com",
                        "Value": "k=rsa; p=MIGfMA0GCSqGS..."
                },
                "DMARC": {
                        "Validation": "Missing Record"
                },
                "SPF": {
                        "Validation": "Verified"
                }
         },
    }
]