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

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

Request:
POST
http://api.createsend.com/api/v3/clients.{xml|json}
Expected Request Body: JSON XML 
 
                    { 
                      "CompanyName": "My Company", 
                      "ContactName": "John", 
                      "EmailAddress": "john@example.com",
                      "Country": "Australia", 
                      "TimeZone": "(GMT+10:00) Canberra, Melbourne, Sydney"
                    }
Expected Response: JSON XML 
 
                    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:

1: Invalid Email

Email address is missing or incorrectly formatted

150: Email Taken

Chosen email address is already being used

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

155: Empty Contact Name

Contact 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 the complete details for a client including their API key, access level, contact details and billing settings.

Request:
GET
http://api.createsend.com/api/v3/clients/{clientid}.{xml|json}
Route Values:
{clientid}

The ID of the client to be retrieved.

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

                    {
                      "ApiKey": "639d8cc27198202f5fe6037a8b17a29a59984b86d3289bc9",
                      "AccessDetails": {
                        "Username": "clientone",
                        "AccessLevel": 23
                      },
                      "BasicDetails": {
                        "ClientID": "4a397ccaaa55eb4e6aa1221e1e2d7122",
                        "CompanyName": "Client One",
                        "ContactName": "Client One (contact)",
                        "EmailAddress": "contact@example.com",
                        "Country": "Australia",
                        "TimeZone": "(GMT+10:00) Canberra, Melbourne, Sydney"
                      },
                      "BillingDetails": {
                         "CanPurchaseCredits": true,
                         "MarkupOnDesignSpamTest": 0.0,
                         "ClientPays": true,
                         "BaseRatePerRecipient": 1.0,
                         "MarkupPerRecipient": 0.0,
                         "MarkupOnDelivery": 0.0,
                         "BaseDeliveryRate": 5.0,
                         "Currency": "USD",
                         "BaseDesignSpamTestRate": 5.0
                      }
                    }
Error Responses:

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

Getting sent campaigns

Returns a list of all sent campaigns for a client including the web version URL, ID, subject, name, date sent and the total number of recipients.

Request:
GET
http://api.createsend.com/api/v3/clients/{clientid}/campaigns.{xml|json}
Route Values:
{clientid}

The ID of the client for which sent campaigns should be retrieved.

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

                    [
                      {
                        "WebVersionURL": "http://hello.createsend.com/t/r-765E86829575EE2C/",
                        "CampaignID": "fc0ce7105baeaf97f47c99be31d02a91",
                        "Subject": "Campaign One",
                        "Name": "Campaign One",
                        "SentDate": "2010-10-12 12:58:00",
                        "TotalRecipients": 2245
                      },
                      {
                        "WebVersionURL": "http://hello.createsend.com/t/r-DD543566A87C9B8B/",
                        "CampaignID": "072472b88c853ae5dedaeaf549a8d607",
                        "Subject": "Campaign Two",
                        "Name": "Campaign Two",
                        "SentDate": "2010-10-06 16:20:00",
                        "TotalRecipients": 11222
                      }
                    ]
Error Responses:

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

Getting scheduled campaigns

Returns all currently scheduled campaigns for a client including the preview URL, ID, subject, name, date created, date scheduled, and the scheduled timezone.

Request:
GET
http://api.createsend.com/api/v3/clients/{clientid}/scheduled.{xml|json}
Route Values:
{clientid}

The ID of the client for which scheduled campaigns should be retrieved.

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

                    [
                      {
                        "DateScheduled": "2011-05-25 10:40:00",
                        "ScheduledTimeZone": "(GMT+10:00) Canberra, Melbourne, Sydney",
                        "CampaignID": "827dbbd2161ea9989fa11ad562c66937",
                        "Name": "Magic Issue One",
                        "Subject": "Magic Issue One",
                        "DateCreated": "2011-05-24 10:37:00",
                        "PreviewURL": "http://hello.createsend.com/t/r-DD543521A87C9B8B/"
                      },
                      {
                        "DateScheduled": "2011-05-29 11:20:00",
                        "ScheduledTimeZone": "(GMT+10:00) Canberra, Melbourne, Sydney",
                        "CampaignID": "4f54bbd2161e65789fa11ad562c66937",
                        "Name": "Magic Issue Two",
                        "Subject": "Magic Issue Two",
                        "DateCreated": "2011-05-24 10:39:00",
                        "PreviewURL": "http://hello.createsend.com/t/r-DD913521A87C9B8B/"
                      }
                    ]
Error Responses:

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

Getting draft campaigns

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

Request:
GET
http://api.createsend.com/api/v3/clients/{clientid}/drafts.{xml|json}
Route Values:
{clientid}

The ID of the client for which draft campaigns should be retrieved.

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

                    [
                      {
                        "CampaignID": "7c7424792065d92627139208c8c01db1",
                        "Name": "Draft One",
                        "Subject": "Draft One",
                        "DateCreated": "2010-08-19 16:08:00",
                        "PreviewURL": "http://hello.createsend.com/t/r-E97A7BB2E6983DA1/"
                      },
                      {
                        "CampaignID": "2e928e982065d92627139208c8c01db1",
                        "Name": "Draft Two",
                        "Subject": "Draft Two",
                        "DateCreated": "2010-08-19 16:08:00",
                        "PreviewURL": "http://hello.createsend.com/t/r-E97A7BB2E6983DA1/"
                      }
                    ]
Error Responses:

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

Getting subscriber lists

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

Request:
GET
http://api.createsend.com/api/v3/clients/{clientid}/lists.{xml|json}
Route Values:
{clientid}

The ID of the client for which subscriber lists should be retrieved.

Expected Response: JSON XML 
                    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 segments

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

Request:
GET
http://api.createsend.com/api/v3/clients/{clientid}/segments.{xml|json}
Route Values:
{clientid}

The ID of the client for which segments should be retrieved.

Expected Response: JSON XML 
                    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

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

Request:
GET
http://api.createsend.com/api/v3/clients/{clientid}/suppressionlist.{xml|json}?page={page}&pagesize={pagesize}&orderfield={email|date}&orderdirection={asc|desc}
Route Values:
{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: JSON XML 
                    HTTP/1.1 200 OK
                    Content-Type: application/json; charset=utf-8

                    {
                      "Results": [
                        {
                          "SuppressionReason": "Bounced",
                          "EmailAddress": "example+1@example.com",
                          "Date": "2010-10-26 10:55:31",
                          "State": "Suppressed"
                        },
                        {
                          "SuppressionReason": "Unsubscribed",
                          "EmailAddress": "example+2@example.com",
                          "Date": "2010-10-26 10:55:31",
                          "State": "Suppressed"
                        },
                        {
                          "SuppressionReason": "Unsubscribed",
                          "EmailAddress": "example+3@example.com",
                          "Date": "2010-10-26 10:55:31",
                          "State": "Suppressed"
                        },
                        {
                          "SuppressionReason": "Reason Unavailable",
                          "EmailAddress": "subscriber@example.com",
                          "Date": "2010-10-25 13:11:04",
                          "State": "Suppressed"
                        },
                        {
                          "SuppressionReason": "Reason Unavailable",
                          "EmailAddress": "subscriberone@example.com",
                          "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

Getting templates

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.

Request:
GET
http://api.createsend.com/api/v3/clients/{clientid}/templates.{xml|json}
Route Values:
{clientid}

The ID of the client for which templates should be retrieved.

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

                    [
                      {
                        "TemplateID": "5cac213cf061dd4e008de5a82b7a3621",
                        "Name": "Template One",
                        "PreviewURL": "http://preview.createsend.com/templates/publicpreview/01AF532CD8889B33?d=r",
                        "ScreenshotURL": "http://preview.createsend.com/ts/r/14/833/263/14833263.jpg?0318092541"
                      },
                      {
                        "TemplateID": "da645c271bc85fb6550acff937c2ab2e",
                        "Name": "Template Two",
                        "PreviewURL": "http://preview.createsend.com/templates/publicpreview/C8A180629495E798?d=r",
                        "ScreenshotURL": "http://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

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

Request:
PUT
http://api.createsend.com/api/v3/clients/{clientid}/setbasics.{xml|json}
Route Values:
{clientid}

The ID of the client for which basic details should be set.

Expected Request Body: JSON XML 
 
                    { 
                      "CompanyName": "My Company", 
                      "ContactName": "John", 
                      "EmailAddress": "john@example.com",
                      "Country": "Australia", 
                      "TimeZone": "(GMT+10:00) Canberra, Melbourne, Sydney"
                    }
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

Email address is missing or incorrectly formatted

150: Email Taken

Chosen email address is already being used

152: Invalid Timezone

Timezone string is not in the correct format. Call User.GetTimezones for a full list.

154: Empty Company Name

Company name cannot be empty

155: Empty Contact Name

Contact name cannot be empty

157: Invalid Country

Country string is either empty or invalid

Setting access settings

Set the level of access this client should have for their account, ranging from no access at all right through to the ability send and pay for their own campaigns. The AccessLevel parameter is an integer which sets exactly which features that client can access. The AccessLevel can be updated for a client without changing the existing login details by omitting the Username/Password parameters from the request.

AccessLevel Reports Subscriber Management Subscriber Imports Create/Send Campaigns Campaign Imports Design and Spam Tests
0 No No No No No No
1 Yes No No No No No
2 No Yes No No No No
3 Yes Yes No No No No
5 Yes No No Yes No No
7 Yes Yes No Yes No No
13 Yes No No Yes No Yes
15 Yes Yes No Yes No Yes
18 No Yes Yes No No No
19 Yes Yes Yes No No No
23 Yes Yes Yes Yes No No
31 Yes Yes Yes Yes No Yes
37 Yes No No Yes Yes No
39 Yes Yes No Yes Yes No
45 Yes No No Yes Yes Yes
47 Yes Yes No Yes Yes Yes
55 Yes Yes Yes Yes Yes No
63 Yes Yes Yes Yes Yes Yes
Request:
PUT
http://api.createsend.com/api/v3/clients/{clientid}/setaccess.{xml|json}
Route Values:
{clientid}

The ID of the client for which access settings should be set.

Expected Request Body: JSON XML 
 
                    { 
                      "Username": "user", 
                      "Password": "password", 
                      "AccessLevel": 23
                    }
Request Body for changing AccessLevel only: JSON XML 
 
                    { 
                      "AccessLevel": 23
                    }
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:

151: Username Taken

The chosen username is already being used, either by the designer or by a client

153: Invalid Access Level

Specified access level does not exist. Please check the valid access level settings.

158: Username Empty

Chosen username cannot be empty when AccessLevel is non zero.

159: Invalid Password

Password must be at least 5 characters in length.

Setting PAYG billing

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

Request:
PUT
http://api.createsend.com/api/v3/clients/{clientid}/setpaygbilling.{xml|json}
Route Values:
{clientid}

The ID of the client for which PAYG billing settings should be set.

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

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

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

Request:
PUT
http://api.createsend.com/api/v3/clients/{clientid}/setmonthlybilling.{xml|json}
Route Values:
{clientid}

The ID of the client for which monthly billing settings should be set.

Expected Request Body: JSON XML 
 
                    { 
                      "Currency": "AUD",
                      "ClientPays": true,
                      "MarkupPercentage": 20,
                    }
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:

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

Deleting a client

Delete an existing client from your account.

Request:
DELETE
http://api.createsend.com/api/v3/clients/{clientid}.{xml|json}
Route Values:
{clientid}

The ID of the client to be deleted.

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.