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

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

{
    "CompanyName": "My Company",
    "Country": "Australia",
    "TimeZone": "(GMT+10:00) Canberra, Melbourne, Sydney"
}

<Client>
    <CompanyName>My Company</CompanyName>
    <Country>Australia</Country>
    <TimeZone>(GMT+10:00) Canberra, Melbourne, Sydney</TimeZone>
</Client>

Expected response: JSON XML

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

"aa164e9c8ab0471294fe6148fc9cf634"

HTTP/1.1 201 Created
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<string>aa164e9c8ab0471294fe6148fc9cf634</string>

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

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

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<Client>
    <ApiKey>639d8cc27198202f5fe6037a8b17a29a59984b86d3289bc9</ApiKey>
    <BasicDetails>
        <ClientID>4a397ccaaa55eb4e6aa1221e1e2d7122</ClientID>
        <CompanyName>Client One</CompanyName>
        <Country>Australia</Country>
        <TimeZone>(GMT+10:00) Canberra, Melbourne, Sydney</TimeZone>
        <PrimaryContactName>Sally</PrimaryContactName>
        <PrimaryContactEmail>[email protected]</PrimaryContactEmail>
        </BasicDetails>
    <BillingDetails>
        <CanPurchaseCredits>true</CanPurchaseCredits>
        <Credits>500</Credits>
        <MarkupOnDesignSpamTest>0.0</MarkupOnDesignSpamTest>
        <ClientPays>true</ClientPays>
        <BaseRatePerRecipient>1.0</BaseRatePerRecipient>
        <MarkupPerRecipient>0.0</MarkupPerRecipient>
        <MarkupOnDelivery>0.0</MarkupOnDelivery>
        <BaseDeliveryRate>5.0</BaseDeliveryRate>
        <Currency>USD</Currency>
        <BaseDesignSpamTestRate>5.0</BaseDesignSpamTestRate>
    </BillingDetails>
</Client>

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

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

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

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<Lists>
    <List>
        <ListID>a58ee1d3039b8bec838e6d1482a8a965</ListID>
        <Name>List One</Name>
    </List>
    <List>
        <ListID>99bc35084a5739127a8ab81eae5bd305</ListID>
        <Name>List Two</Name>
    </List>
</Lists>

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

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"
    }
]

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<Lists>
    <List>
        <DateSubscriberAdded>2010-03-19 11:15:00</DateSubscriberAdded>
        <ListID>a58ee1d3039b8bec838e6d1482a8a965</ListID>
        <ListName>List One</ListName>
        <SubscriberState>Active</SubscriberState>
    </List>
    <List>
        <DateSubscriberAdded>2011-04-01 01:27:00</DateSubscriberAdded>
        <ListID>99bc35084a5739127a8ab81eae5bd305</ListID>
        <ListName>List Two</ListName>
        <SubscriberState>Unsubscribed</SubscriberState>
    </List>
</Lists>

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: 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"
    }
]

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<Segments>
    <Segment>
        <ListID>a58ee1d3039b8bec838e6d1482a8a965</ListID>
        <SegmentID>46aa5e01fd43381863d4e42cf277d3a9</SegmentID>
        <Title>Segment One</Title>
    </Segment>
    <Segment>
        <ListID>8dffb94c60c5faa3d40f496f2aa58a8a</ListID>
        <SegmentID>dhw9q8jd9q8wd09quw0d909wid9i09iq</SegmentID>
        <Title>Segment Two</Title>
    </Segment>
</Segments>

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

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
}

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<PagedResult>
    <Results>
        <Subscriber>
            <CustomFields />
            <Date>2010-10-26 10:55:31</Date>
            <EmailAddress>[email protected]</EmailAddress>
            <Name />
            <State>Suppressed</State>
            <SuppressionReason>Bounced</SuppressionReason>
        </Subscriber>
        <Subscriber>
            <CustomFields />
            <Date>2010-10-26 10:55:31</Date>
            <EmailAddress>[email protected]</EmailAddress>
            <Name />
            <State>Suppressed</State>
            <SuppressionReason>Unsubscribed</SuppressionReason>
        </Subscriber>
        <Subscriber>
            <CustomFields />
            <Date>2010-10-26 10:55:31</Date>
            <EmailAddress>[email protected]</EmailAddress>
            <Name />
            <State>Suppressed</State>
            <SuppressionReason>Unsubscribed</SuppressionReason>
        </Subscriber>
        <Subscriber>
            <CustomFields />
            <Date>2010-10-25 13:11:04</Date>
            <EmailAddress>[email protected]</EmailAddress>
            <Name />
            <State>Suppressed</State>
            <SuppressionReason>Reason Unavailable</SuppressionReason>
        </Subscriber>
        <Subscriber>
            <CustomFields />
            <Date>2010-10-25 13:04:15</Date>
            <EmailAddress>[email protected]</EmailAddress>
            <Name />
            <State>Suppressed</State>
            <SuppressionReason>Reason Unavailable</SuppressionReason>
        </Subscriber>
    </Results>
    <ResultsOrderedBy>email</ResultsOrderedBy>
    <OrderDirection>asc</OrderDirection>
    <PageNumber>1</PageNumber>
    <PageSize>1000</PageSize>
    <RecordsOnThisPage>5</RecordsOnThisPage>
    <TotalNumberOfRecords>5</TotalNumberOfRecords>
    <NumberOfPages>1</NumberOfPages>
</PagedResult>

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

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

{
    "EmailAddresses": [ "[email protected]", "[email protected]" ]
}

<SuppressionDetails>
    <EmailAddresses>
        <EmailAddress>[email protected]</EmailAddress>
        <EmailAddress>[email protected]</EmailAddress>
    </EmailAddresses>
</SuppressionDetails>

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

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"
    }
]

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<Templates>
    <Template>
        <Name>Template One</Name>
        <PreviewURL>https://preview.createsend.com/templates/publicpreview/01AF532CD8889B33?d=r</PreviewURL>
        <ScreenshotURL>https://preview.createsend.com/ts/r/14/833/263/14833263.jpg?0318092541</ScreenshotURL>
        <TemplateID>5cac213cf061dd4e008de5a82b7a3621</TemplateID>
    </Template>
    <Template>
        <Name>Template Two</Name>
        <PreviewURL>https://preview.createsend.com/templates/publicpreview/C8A180629495E798?d=r</PreviewURL>
        <ScreenshotURL>https://preview.createsend.com/ts/r/18/7B3/552/187B3552.jpg?0705043527</ScreenshotURL>
        <TemplateID>da645c271bc85fb6550acff937c2ab2e</TemplateID>
    </Template>
</Templates>

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

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

{
    "CompanyName": "My Company",
    "Country": "Australia",
    "TimeZone": "(GMT+10:00) Canberra, Melbourne, Sydney"
}

<Client>
    <CompanyName>My Company</CompanyName>
    <Country>Australia</Country>
    <TimeZone>(GMT+10:00) Canberra, Melbourne, Sydney</TimeZone>
</Client>

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

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
}

<BillingOptions>
    <Currency>AUD</Currency>
    <CanPurchaseCredits>false</CanPurchaseCredits>
    <ClientPays>true</ClientPays>
    <MarkupPercentage>20</MarkupPercentage>
    <MarkupOnDelivery>5</MarkupOnDelivery>
    <MarkupPerRecipient>4</MarkupPerRecipient>
    <MarkupOnDesignSpamTest>3</MarkupOnDesignSpamTest>
</BillingOptions>

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 Premier. Note 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: JSON XML

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

{
    "Currency": "AUD",
    "ClientPays": true,
    "MarkupPercentage": 20,
    "MonthlyScheme": "Basic",
}

<BillingOptions>
    <Currency>AUD</Currency>
    <ClientPays>true</ClientPays>
    <MarkupPercentage>20</MarkupPercentage>
    <MonthlyScheme>Basic</MonthlyScheme>
</BillingOptions>

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

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

{
    "Credits": 200,
    "CanUseMyCreditsWhenTheyRunOut": false
}

<TransferCredits>
    <Credits>200</Credits>
    <CanUseMyCreditsWhenTheyRunOut>false</CanUseMyCreditsWhenTheyRunOut>
</TransferCredits>

Expected response: JSON XML

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

{
    "AccountCredits": 800,
    "ClientCredits": 200
}

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<TransferCreditsResult>
    <AccountCredits>800</AccountCredits>
    <ClientCredits>200</ClientCredits>
</TransferCreditsResult>

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:

clientid The ID of the client to add the person to.

Expected request: JSON XML

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

{
  "EmailAddress": "[email protected]",
  "Name": "Sally Sparrow",
  "AccessLevel": 23,
  "Password": "opensesame"
}

<AddPerson>
  <EmailAddress>[email protected]</EmailAddress>
  <Name>Sally Sparrow</Name>
  <AccessLevel>23</AccessLevel>
  <Password>opensesame</Password>
</AddPerson>

Expected response: JSON XML

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

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

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<AddPersonResponse>
    <EmailAddress>[email protected]</EmailAddress>
</AddPersonResponse>

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.

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

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

{
  "EmailAddress": "[email protected]",
  "Name": "Sam Sparrow",
  "AccessLevel": 31,
  "Password": "opensesame"
}

<UpdatePerson>
  <EmailAddress>[email protected]</EmailAddress>
  <Name>Sam Sparrow</Name>
  <AccessLevel>31</AccessLevel>
  <Password>opensesame</Password>
</UpdatePerson>

Expected response: JSON XML

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

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

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<UpdatePersonResponse>
    <EmailAddress>[email protected]</EmailAddress>
</UpdatePersonResponse>

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

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"
  }
]

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<People>
    <Person>
        <EmailAddress>[email protected]</EmailAddress>
        <Name>Sally Sparrow</Name>
        <AccessLevel>31</AccessLevel>
        <Status>Waiting to Accept the Invitation</Status>
    </Person>
    <Person>
        <EmailAddress>[email protected]</EmailAddress>
        <Name>John Jones</Name>
        <AccessLevel>23</AccessLevel>
        <Status>Active</Status>
    </Person>
</People>

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

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

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

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<Person>
    <EmailAddress>[email protected]</EmailAddress>
    <Name>John Jones</Name>
    <AccessLevel>23</AccessLevel>
    <Status>Active</Status>
</Person>

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

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

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

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<PrimaryContact>
    <EmailAddress>[email protected]</EmailAddress>
</PrimaryContact>

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

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

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

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<PrimaryContact>
    <EmailAddress>[email protected]</EmailAddress>
</PrimaryContact>

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

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

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

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfClientTag>
    <ClientTag>
        <Name>Monthly promo</Name>
        <NumberOfCampaigns>120</NumberOfCampaigns>
    </ClientTag>
    <ClientTag>
        <Name>Marketing tips</Name>
        <NumberOfCampaigns>62</NumberOfCampaigns>
    </ClientTag>
</ArrayOfClientTag>

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

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
}

<PagedResult>
    <NumberOfPages>1</NumberOfPages>
    <OrderDirection>desc</OrderDirection>
    <PageNumber>1</PageNumber>
    <PageSize>1000</PageSize>
    <RecordsOnThisPage>1</RecordsOnThisPage>
    <Results>
        <Campaign>
            <FromEmail>[email protected]</FromEmail>
            <FromName>My Name</FromName>
            <Name>Campaign One</Name>
            <ReplyTo>[email protected]</ReplyTo>
            <SentDate>2020-10-12 12:58:00</SentDate>
            <TotalRecipients>2245</TotalRecipients>
            <CampaignID>fc0ce7105baeaf97f47c99be31d02a91</CampaignID>
            <Subject>Campaign One</Subject>
            <Tags>
                <string>2020</string>
                <string>COVID-19</string>
            </Tags>
            <WebVersionURL>https://createsend.com/t/r-765E86829575EE2C/</WebVersionURL>
            <WebVersionTextURL>https://createsend.com/t/r-765E86829575EE2C/t</WebVersionTextURL>
        </Campaign>
        <Campaign>
            <FromEmail>[email protected]</FromEmail>
            <FromName>My Name</FromName>
            <Name>Campaign Two</Name>
            <ReplyTo>[email protected]</ReplyTo>
            <SentDate>2020-10-06 16:20:00</SentDate>
            <TotalRecipients>11222</TotalRecipients>
            <CampaignID>072472b88c853ae5dedaeaf549a8d607</CampaignID>
            <Subject>Campaign Two</Subject>
            <Tags>
                <string>Charity</string>
                <string>COVID-19</string>
            </Tags>
            <WebVersionURL>https://createsend.com/t/r-DD543566A87C9B8B/</WebVersionURL>
            <WebVersionTextURL>https://createsend.com/t/r-DD543566A87C9B8B/t</WebVersionTextURL>
        </Campaign>
    </Results>
    <ResultsOrderedBy>SentDate</ResultsOrderedBy>
    <TotalNumberOfRecords>5</TotalNumberOfRecords>
</PagedResult>

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

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": []
    }
]

<?xml version="1.0" encoding="utf-8"?>
<DetailedScheduledCampaigns>
    <Campaign>
        <CampaignID>827dbbd2161ea9989fa11ad562c66937</CampaignID>
        <DateCreated>2021-05-24 10:37:00</DateCreated>
        <FromEmail>[email protected]</FromEmail>
        <FromName>My Name</FromName>
        <Name>Magic Issue One</Name>
        <PreviewTextURL>https://createsend.com/t/r-DD543521A87C9B8B/t</PreviewTextURL>
        <PreviewURL>https://createsend.com/t/r-DD543521A87C9B8B/</PreviewURL>
        <ReplyTo>[email protected]</ReplyTo>
        <Subject>Magic Issue One</Subject>
        <DateScheduled>2022-05-25 10:40:00</DateScheduled>
        <ScheduledTimeZone>(GMT-05:00) Eastern Time (US &amp; Canada)</ScheduledTimeZone>
        <Tags>
            <string>morning</string>
        </Tags>
    </Campaign>
    <Campaign>
        <CampaignID>4f54bbd2161e65789fa11ad562c66937</CampaignID>
        <DateCreated>2021-05-24 10:39:00</DateCreated>
        <FromEmail>[email protected]</FromEmail>
        <FromName>My Name</FromName>
        <Name>Magic Issue Two</Name>
        <PreviewTextURL>https://createsend.com/t/r-DD913521A87C9B8B/t</PreviewTextURL>
        <PreviewURL>https://createsend.com/t/r-DD913521A87C9B8B/</PreviewURL>
        <ReplyTo>[email protected]</ReplyTo>
        <Subject>Magic Issue Two</Subject>
        <DateScheduled>2022-05-25 10:40:00</DateScheduled>
        <ScheduledTimeZone>(GMT-05:00) Eastern Time (US &amp; Canada)</ScheduledTimeZone>
        <Tags />
    </Campaign>    
</DetailedScheduledCampaigns>

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

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"
        ]
    }
]

<?xml version="1.0" encoding="utf-8"?>
<DetailedDrafts>
    <Campaign>
        <CampaignID>7c7424792065d92627139208c8c01db1</CampaignID>
        <DateCreated>2021-08-19 16:08:00</DateCreated>
        <FromEmail>[email protected]</FromEmail>
        <FromName>My Name</FromName>
        <Name>Draft One</Name>
        <PreviewTextURL>https://createsend.com/t/r-E97A7BB2E6983DA1/t</PreviewTextURL>
        <PreviewURL>https://createsend.com/t/r-E97A7BB2E6983DA1/</PreviewURL>
        <ReplyTo>[email protected]</ReplyTo>
        <Subject>Draft One</Subject>
        <Tags>
            <string>discount</string>
            <string>halloween</string>
        </Tags>
    </Campaign>
    <Campaign>
        <CampaignID>2e928e982065d92627139208c8c01db1</CampaignID>
        <DateCreated>2021-08-19 16:08:00</DateCreated>
        <FromEmail>[email protected]</FromEmail>
        <FromName>My Name</FromName>
        <Name>Draft Two</Name>
        <PreviewTextURL>https://createsend.com/t/r-E97A7BB2E6983DA1/t</PreviewTextURL>
        <PreviewURL>https://createsend.com/t/r-E97A7BB2E6983DA1/</PreviewURL>
        <ReplyTo>[email protected]</ReplyTo>
        <Subject>Draft Two</Subject>
        <Tags>
            <string>halloween</string>
        </Tags>
    </Campaign>
</DetailedDrafts>

Error responses:

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

Getting sending domains

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

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"
                }
         },
    },
]

<?xml version="1.0" encoding="utf-8"?>
<SendingDomainCollectionResult>
    <SendDomainResult>
        <DNSRecords>
            <DKIM>
                <Key>cm._domainkey.example.com</Key>
                <Validation>Verified</Validation>
                <Value>k=rsa; p=MIGfMA0GCSqGS...</Value>
            </DKIM>
            <DMARC>
                <Validation>Missing Record</Validation>
            </DMARC>
            <SPF>
                <Validation>Verified</Validation>
            </SPF>
        </DNSRecords>
        <PublicKey>MIGfMA0GCSqGS.....</PublicKey>
        <Selector>cm</Selector>
        <SendingDomain>example.com</SendingDomain>
    </SendDomainResult>
    <SendDomainResult>
        <DNSRecords>
            <DKIM>
                <Key>cm._domainkey.test.com</Key>
                <Validation>Verified</Validation>
                <Value>k=rsa; p=MIGfMA0GCSqGS...</Value>
            </DKIM>
            <DMARC>
                <Validation>Verified</Validation>
            </DMARC>
            <SPF>
                <Validation>Verified</Validation>
            </SPF>
        </DNSRecords>
         <PublicKey>MIGfMA0GCSqGS...</PublicKey>
        <Selector>cm</Selector>
        <SendingDomain>test.com</SendingDomain>
    </SendDomainResult>
</SendingDomainCollectionResult>

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

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

{
    "SendingDomain": "example.com",
    "Selector": "myCustomSelector",
    "PublicKey": "MIGfMA0GCSqGS...",
    "PrivateKey": "MIICXQIBAAKBgQ...",
}

<SendingDomainRequest>
    <SendingDomain>example.com</SendingDomain>
    <Selector>myCustomSelector</Selector>
    <PublicKey>MIGfMA0GCSqGS...</PublicKey>
    <PrivateKey>MIICXQIBAAKBgQ...</PrivateKey>
</SendingDomainRequest>

Expected response: JSON XML

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": "myCustomSelector._domainkey.example.com",
                        "Value": "k=rsa; p=MIGfMA0GCSqGS..."
                },
                "DMARC": {
                        "Validation": "Verified"
                },
                "SPF": {
                        "Validation": "Verified"
                }
         },
 }

<?xml version="1.0" encoding="utf-8"?>
<SendingDomainModel>
    <DNSRecords>
        <DKIM>
            <Key>myCustomSelector._domainkey.example.com</Key>
            <Validation>Missing record</Validation>
            <Value>k=rsa;
                p=MIGfMA0GCSqGS...
            </Value>
        </DKIM>
        <DMARC>
            <Validation>Verified</Validation>
        </DMARC>
        <SPF>
            <Validation>Verified</Validation>
        </SPF>
    </DNSRecords>
    <PublicKey>MIGfMA0GCSqGS...</PublicKey>
    <Selector>myCustomSelector</Selector>
    <SendingDomain>example.com</SendingDomain>
</SendingDomainModel>

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 Domain name not valid You attempted to supply a domain name that is not valid
3502 Domain name is free email domain You attempted to supply a free domain name which is not valid
3503 Domain name registration failure You attempted to supply a domain that has not been registered correctly
3504 Domain exists in this account You attempted to create a sending domain that already exists for this account
3505 Domain exists in another account You attempted to create a sending domain that already exists in another account
3506 Domain exists in this client You attempted to create a sending domain that already exists in this client
3507 Invalid selector You attempted to pass in an invalid selector
3508 Invalid public key You attempted to pass in an invalid public key
3509 Invalid private key You attempted to pass in an invalid private key
3512 Domain and selector exists in another account You attempted to create a sending domain and selector that already exists in another account
3513 Domain and selector exists in this account You attempted to create a sending domain and selector that already exists for this account
3514 Domain and selector exists in this client You attempted to create a sending domain and selector that 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 Domain selector combination not found You attempted to pass in a domain name and selector combination that cannot 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: JSON XML

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

{
    "DestinationClientID": "da694f4852b355",
    "SendingDomain": "example.com",
    "Selector": "cm"
}

<SendingDomainRequest>
    <SendingDomain>example.com</SendingDomain>
    <Selector>cm</Selector>
    <DestinationClientID>da694f4852b355</DestinationClientID>
</SendingDomainRequest>

Expected response: JSON XML

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

HTTP/1.1 201 Created
Content-Type: application/xml; 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 Invalid destination client ID Invalid DestinationClientID
3501 Domain name not valid You attempted to supply a domain name that is not valid
3507 Invalid selector You attempted to pass in an invalid selector
3510 Domain selector combination not found You attempted to pass in a domain name and selector combination that cannot 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: JSON XML

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"
                }
         },
    }
]

<?xml version="1.0" encoding="utf-8"?>
<SendingDomainCollectionResult>
    <SendDomainResult>
        <DNSRecords>
            <DKIM>
                <Key>cm._domainkey.example.com</Key>
                <Validation>Verified</Validation>
                <Value>k=rsa;
                    p=MIGfMA0GCSqGS...
                </Value>
            </DKIM>
            <DMARC>
                <Validation>Missing Record</Validation>
            </DMARC>
            <SPF>
                <Validation>Verified</Validation>
            </SPF>
        </DNSRecords>
        <PublicKey>MIGfMA0GCSqGS...</PublicKey>
        <Selector>cm</Selector>
        <SendingDomain>example.com</SendingDomain>
    </SendDomainResult>
</SendingDomainCollectionResult>

Our API

Clients

Creating a client

Error responses:

Getting a client’s details

Error responses:

Getting subscriber lists

Error responses:

Getting lists for an email address

Error responses:

Getting segments

Error responses:

Getting suppression list

Error responses:

Suppress email addresses

Error responses:

Unsuppress an email address

Error responses:

Getting templates

Error responses:

Setting basic details

Error responses:

Setting PAYG billing

Error responses:

Setting monthly billing

Error responses:

Transfer credits

Error responses:

Deleting a client

Error responses:

Adding a person

Error responses:

Updating a person

Error responses:

Getting people

Error responses:

Person details

Error responses:

Deleting a Person

Error responses:

Setting primary contact

Error responses:

Getting primary contact

Error responses:

Getting tags

Error responses:

Getting sent campaigns

Error responses:

Getting scheduled campaigns

Error responses:

Getting draft campaigns

Error responses:

Getting sending domains

Error responses:

Adding a sending domain

Error responses:

Delete a sending domain

Error responses:

Copy a sending domain to another client

Error responses:

Verify sending domains