Our API

Campaigns

Covers all the campaign related functionality including creating draft campaigns, selecting recipients and sending. Once the campaign is sent, you can also access all the reporting data on the results.


Creating a draft campaign

Creates (but does not send) a draft campaign ready to be tested as a preview or sent. Set the basic campaign information (name, subject, from name and from email), the URL of the HTML content plus the lists and/or segments you'd like it to be eventually sent to. We'll automatically move all CSS inline for the HTML component.

Note that you may optionally specify a TextUrl field in your input if you want to specify text content for the campaign. If you don't specify TextUrl or if TextUrl is left empty, the text content for the campaign will be automatically generated from the HTML content.

clientid The ID of the client for whom the campaign should be created. You can get this ID by getting your clients.

POST https://api.createsend.com/api/v3.1/campaigns/{clientid}.{xml|json}
Expected body request: JSON XML
{
    "Name": "My Campaign Name",
    "Subject": "My Subject",
    "FromName": "My Name",
    "FromEmail": "myemail@mydomain.com",
    "ReplyTo": "myemail@mydomain.com",
    "HtmlUrl": "http://example.com/campaigncontent/index.html",
    "ListIDs": [
        "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
        "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1"
    ],
    "SegmentIDs": [
        "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
        "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1"
    ]
}
Expected response: JSON XML
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
 
"a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1"
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:

  • 303: Duplicate Campaign Name The campaign name passed in already exists for this client.
  • 304: Campaign Subject Required A campaign subject must be provided.
  • 305: From Name Required The From name field is required and must be provided.
  • 307: Invalid From Email Address The From Email Address must be a valid email address.
  • 308: Reply to Address Required The Reply-To Address is a required field and must be provided.
  • 309: Invalid Reply-To Address The Reply-To Address must be a valid email address.
  • 310: HTML Content URL Required You must provide a URL of the HTML content for your campaign.
  • 311: Invalid HTML Content Your content contains JavaScript or Flash which cannot be sent to email clients.
  • 312: Invalid Text Content URL Text Content URL is optional, but must be valid if provided.
  • 313: Invalid ListID’s The List ID’s you supplied are invalid.
  • 314: Invalid Segments The Segments you supplied are invalid.
  • 315: Lists or Segments Required You must provide either List ID’s or Segments to send to.
  • 316: Problems Importing Links There was a problem parsing and importing your links.
  • 317: Link Too Long At least one of your links was too long to import.
  • 318: Text Unsubscribe Tag In HTML Email You currently only have a text unsubscribe link of the format {[unsubscribe]} in your HTML content. We require a single-click unsubscribe link in every campaign you send. You can do this by adding the tags and around the words you want to become an unsubscribe link, and then re-import your content.
  • 319: Campaign Name Required A campaign name was not provided, and is required.
  • 4302: Unsubscribe Tag Contains Less Than 3 Chars You'll need to add some text, such as 'unsubscribe' in between your and tags. Those words will then become an unsubscribe link for each recipient.
  • 4303: Unsubscribe Tag Contains A Link It appears your <unsubscribe> tag contains a link. Please ensure you add the tags and around only the words (and not links) you want to become an unsubscribe link. We'll automatically convert that to a link for each recipient.
  • 4304: No Closing Unsubscribe Tag We found the <unsubscribe> tag, but couldn't track down the </unsubscribe> tag. You'll need to add this before the unsubscribe link will work.
  • 4306: Nested Unsubscribe tag We've detected an <unsubscribe> tag inside another Campaign Monitor tag. This will render the Unsubscribe link unusable, and can cause problems with your subscribers attempting to unsubscribe. Please place the <unsubscribe> tag outside the Campaign Monitor tag.
  • 4307: Nested Unsubscribe tag We've detected an <unsubscribe> tag inside another link (ie. an <a> tag). This will render the Unsubscribe link unusable, and can cause problems with your subscribers attempting to unsubscribe. Please place the <unsubscribe> tag outside the link.
  • 4201: Contains Flash Flash is not supported by almost every email client out there and should not be included in your emails.
  • 4203: Contains Java Java is not supported by almost every email client out there and should not be included in your emails. Please remove it from your content.
  • 4202: Contains Script Almost every popular email client and spam filter does not support JavaScript. Your campaign will either be filtered as spam, or will display a security warning to your recipients. We recommend removing all JavaScript code from your campaign and then re-import it.

Creating a campaign from a template

Creates (but does not send) a draft campaign based on a template ready to be tested as a preview or sent. Set the basic campaign information (name, subject, from name and from email), the template ID, the template content, plus the lists and/or segments you'd like it to be eventually sent to. You can find the template ID you want to use by getting a client's templates.

clientid The ID of the client for whom the campaign should be created. You can get this ID by getting your clients.

POST https://api.createsend.com/api/v3.1/campaigns/{clientid}/fromtemplate.{xml|json}

If you had the following HTML markup in your template:

Example template HTML:
<html>
  <head><title>My Template</title></head>
  <body>
    <p><singleline>Enter heading...</singleline></p>
    <div><multiline>Enter description...</multiline></div>
    <img id="header-image" editable="true" width="500" />
    <repeater>
      <layout label="My layout">
        <div class="repeater-item">
          <p><singleline></singleline></p>
          <div><multiline></multiline></div>
          <img editable="true" width="500" />
        </div>
      </layout>
    </repeater>
    <p><unsubscribe>Unsubscribe</unsubscribe></p>
  </body>
</html>

You'd make a request similar to the following:

Expected body request: JSON XML
{
  "Name": "My Campaign Name",
  "Subject": "My Subject",
  "FromName": "My Name",
  "FromEmail": "myemail@mydomain.com",
  "ReplyTo": "myemail@mydomain.com",
  "ListIDs": [
    "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
    "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1"
  ],
  "SegmentIDs": [
    "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
    "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1"
  ],
  "TemplateID": "89qw8du9q7y87yd8quw98udwqdqwd",
  "TemplateContent": {
    "Singlelines": [
      {
        "Content": "This is a heading",
        "Href": "http://example.com/"
      }
    ],
    "Multilines": [
      {
        "Content": "<p>This is example</p><p>multiline <a href=\"http://example.com\">content</a>...</p>"
      }
    ],
    "Images": [
      {
        "Content": "http://example.com/image.png",
        "Alt": "This is alt text for an image",
        "Href": "http://example.com/"
      }
    ],
    "Repeaters": [
      {
        "Items": [
          {
            "Layout": "My layout",
            "Singlelines": [
              {
                "Content": "This is a repeater heading",
                "Href": "http://example.com/"
              }
            ],
            "Multilines": [
              {
                "Content": "<p>This is example</p><p>multiline <a href=\"http://example.com\">content</a>...</p>"
              }
            ],
            "Images": [
              {
                "Content": "http://example.com/repeater-image.png",
                "Alt": "This is alt text for a repeater image",
                "Href": "http://example.com/"
              }
            ]
          }
        ]
      }
    ]
  }
}

SinglelinesRepresents content for floating singleline tags. Each entry should contain:

  • Content The content to populate the singleline tag in the template.
  • Href Optional URL to be used as a link for the singleline content.

MultilinesRepresents content for floating multiline tags. Each entry should contain:

  • Content The content to populate the multiline tag in the template.

ImagesRepresents content for floating editable image tags. Each entry should contain:

  • Content The URL of the image to be downloaded and used in the template.
  • Href Optional URL to be used as a link for the image.
  • Alt Optional alternate text for the image.

RepeatersRepresents content for repeaters. Each repeater should contain an Items collection. Each repeater item should contain:

  • Layout Optional layout identifier if a specific layout is being targeted in the repeater.
  • Singlelines Should be formatted in the same way as described above for floating singleline tags.
  • Multilines Should be formatted in the same way as described above for floating multiline tags.
  • Images Should be formatted in the same way as described above for floating editable image tags.

It is important to note that all content provided in the request body (singlelines, multilines, images, and repeaters), will be matched with their corresponding template tags in the order in which they are found in the template.

If you wish to skip an editable image in the template and use the default image, simply pass an empty string as the value for the Content field for the image.

Also note that use of datarepeater tags is not yet supported when using the API to create a campaign from a template.

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

"a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1"

As a result of this call, the resulting campaign would be composed similarly to:

Resulting campaign HTML:
<html>
  <head><title>My Template</title></head>
  <body>
    <p><a href="http://example.com/">This is a heading</a></p>
    <div><p>This is example</p><p>multiline <a href="http://example.com/">content</a>...</p></div>
    <a href="http://example.com/"><img id="header-image" width="500" src="http://i1.createsend.com/ei/.../image.png" height="375" alt="This&#32;is&#32;alt&#32;text&#32;for&#32;an&#32;image" /></a>
    <div class="repeater-item">
      <p><a href="http://example.com/">This is a repeater heading</a></p>
      <div><p>This is example</p><p>multiline <a href="http://example.com/">content</a>...</p></div>
      <a href="http://example.com/"><img width="500" src="http://i1.createsend.com/ei/.../repeater-image.png" height="375" alt="This&#32;is&#32;alt&#32;text&#32;for&#32;a&#32;repeater&#32;image" /></a>
    </div>
    <p><a href="http://t.createsend.com/t/.../">Unsubscribe</a></p>
  </body>
</html>
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:

  • 303: Duplicate Campaign Name The campaign name passed in already exists for this client.
  • 304: Campaign Subject Required A campaign subject must be provided.
  • 305: From Name Required The From name field is required and must be provided.
  • 307: Invalid From Email Address The From Email Address must be a valid email address.
  • 308: Reply to Address Required The Reply-To Address is a required field and must be provided.
  • 309: Invalid Reply-To Address The Reply-To Address must be a valid email address.
  • 313: Invalid ListID’s The List ID’s you supplied are invalid.
  • 314: Invalid Segments The Segments you supplied are invalid.
  • 315: Lists or Segments Required You must provide either List ID’s or Segments to send to.
  • 319: Campaign Name Required A campaign name was not provided, and is required.
  • 320: Template Content Required Template content must be provided.
  • 321: Template Content Includes Invalid Image Template content includes an image with an invalid URL, which we couldn't download.
  • 4001: Invalid Template ID Invalid Template ID, or the template doesn't exist or belong to the client.

Sending a draft campaign

Schedules an existing draft campaign for sending either immediately or a custom date and time in the future. For campaigns with more than 5 recipients, you must have sufficient email credits, a saved credit card or an active monthly billed account.

Free sending limitation: When sending campaigns to 5 or less recipients (which are free of charge), you can send to a maximum of 50 unique email addresses per day.

campaignid The ID of the campaign draft to be sent. You can get the ID as the result of creating a campaign, or by getting draft campaigns.

POST https://api.createsend.com/api/v3.1/campaigns/{campaignid}/send.{xml|json}
Expected body request: JSON XML
{
    "ConfirmationEmail": "confirmation@example.com, another@example.com",
    "SendDate": "YYYY-MM-DD HH:MM"
}

ConfirmationEmail An email address (or a maximum of five comma-separated email addresses) to which we'll send a confirmation email once your campaign has been sent.

SendDate The date the campaign should be scheduled to be sent. To send a campaign immediately pass in Immediately. This date should be in the client's timezone and formatted as YYYY-MM-DD HH:MM.

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.

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:

  • 5: Invalid Date The Send Date provided was invalid.
  • 331: Campaign has already been sent The campaign has already been sent.
  • 332: No Recipients Added There are no recipient lists or segments added to this campaign.
  • 333: No Test Campaigns Available Each customer can send a limited number of test campaigns (of less than 6 recipients). Contact support if you have any queries.
  • 334: Campaign Pending Approval This client doesn't have approval to send to a list of recipients of this size.
  • 335: Payment Details Required The payment details for this client are required.
  • 336: Campaign Payment Failed Payment for this campaign failed. Either there weren’t sufficient credits or the payment details were rejected.
  • 337: Delivery Date Cannot be in the Past The delivery date was set to a date in the past.
  • 338: Confirm Email Required The email address for campaign sent confirmation cannot be empty.
  • 339: Confirm Email Invalid The email address for campaign sent confirmation is invalid.
  • 340: Recipient Lists Empty The selected subscriber lists and/or segments contain no subscribers
  • 355: Monthly Payment Failed Your monthly account has not been paid for, and the attempt to bring it up to date failed.

Sending a campaign preview

Send a preview of any draft campaign to a number of email addresses you specify. You can also set how we should treat any personalization tags in your draft campaign.

campaignid The ID of the campaign draft being tested. You can get the ID as the result of creating a campaign, or via the getting draft campaigns.

POST https://api.createsend.com/api/v3.1/campaigns/{campaignid}/sendpreview.{xml|json}
Expected request body: JSON XML
{
    "PreviewRecipients": ["test1@example.com", "test2@example.com"],
    "Personalize": "Random"
}

PreviewRecipients A collection of intended recipients of the campaign preview.

Personalize Option to control personalization of the campaign preview. Only relevant when the campaign actually includes personalization tags. Valid variations are:

  • Fallback Use the fallback terms.
  • Random Choose a random recipient from the lists and segments allocated to the campaign.
  • A specific email address Use the personalisation details attached to the email address. Only valid if the subscriber is a recipient of the campaign. The address will not be sent a copy of the email.

Expected response (both XML and JSON):

HTTP/1.1 200 OK
Error responses:

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

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

  • 333: No Test Campaigns Available Each customer can send a limited number of test campaigns (of less than 6 recipients). Contact support if you have any queries.
  • 340: Recipient Lists Empty The selected subscriber lists and/or segments contain no subscribers
  • 370: No Preview Recipients Supplied Preview Recipients must have at least one email address.
  • 371: Invalid Preview Recipient Emails Preview Recipients must all be valid email addresses. A collection of Recipients to indicate which intended recipients were invalid email addresses is also returned.
    <Result>
        <Code>371</Code>
        <Message>PreviewRecipients must all be valid email addresses</Message>
        <ResultData>
            <Recipient>test1@malformedemail</Recipient>
            <Recipient>not_even_close</Recipient>
        </ResultData>
    </Result>
  • 372: Invalid Personalization Data Personalize must be one of Fallback, Random, or a valid email address.
  • 373: Recipient Not In Campaign Lists Personalisation email address must be a recipient of the campaign.
  • 374: Too Many Preview Recipients You can only send to fifteen (15) addresses at once.
  • 375: Client Test Campaign Rate Violation You can only send to 240 addresses every 1440 minutes (24 hours).
  • 376: Campaign Must Have Content And Recipients Campaign must have content and recipient lists assigned.

Campaign summary

Provides a basic summary of the results for any sent campaign such as the number of recipients, opens, clicks, unsubscribes, etc to date. Also includes the web version URL, and the public Worldview URL for the campaign.

campaignid The ID of the campaign you want data for. Get the ID by getting sent campaigns.

GET https://api.createsend.com/api/v3.1/campaigns/{campaignid}/summary.{xml|json}
Expected response: JSON XML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
 
{
    "Recipients": 1000,
    "TotalOpened": 345,
    "Clicks": 132,
    "Unsubscribed": 43,
    "Bounced": 15,
    "UniqueOpened": 298,
    "SpamComplaints": 23,
    "WebVersionURL": "http://createsend.com/t/y-A1A1A1A1A1A1A1A1A1A1A1A1/",
    "WebVersionTextURL": "http://createsend.com/t/y-A1A1A1A1A1A1A1A1A1A1A1A1/t",
    "WorldviewURL": "http://myclient.createsend.com/reports/wv/y/8WY898U9U98U9U9",
    "Forwards": 18,
    "Likes": 25,
    "Mentions": 11
}
Error responses:
Please see our response status codes documentation for details of potential error responses for any API request.

Campaign email client usage

Lists the email clients subscribers used to open the campaign. Each entry includes the email client name, the email client version, the percentage of subscribers who used it, and the actual number of subscribers who used it to open the campaign.

campaignid The ID of the campaign you want data for. Get the ID by getting sent campaigns.

GET https://api.createsend.com/api/v3.1/campaigns/{campaignid}/emailclientusage.{xml|json}
Expected response: JSON XML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "Client": "iOS Devices",
        "Version": "iPhone",
        "Percentage": 19.83,
        "Subscribers": 7056
    },
    {
        "Client": "Apple Mail",
        "Version": "Apple Mail 6",
        "Percentage": 13.02,
        "Subscribers": 4633
    },
    {
        "Client": "Apple Mail",
        "Version": "Apple Mail 5",
        "Percentage": 10.60,
        "Subscribers": 3773
    },
    {
        "Client": "Microsoft Outlook",
        "Version": "Outlook 2010",
        "Percentage": 7.18,
        "Subscribers": 2556
    },
    {
        "Client": "iOS Devices",
        "Version": "iPad",
        "Percentage": 4.43,
        "Subscribers": 1577
    },
    {
        "Client": "Undetectable",
        "Version": "Undetectable",
        "Percentage": 4.94,
        "Subscribers": 1632
    }
]
Error responses:
Please see our response status codes documentation for details of potential error responses for any API request.

Campaign lists and segments

Returns the lists and segments any campaign was sent to.
campaignid The ID of the campaign you want data for. Get the ID by getting sent campaigns.

GET https://api.createsend.com/api/v3.1/campaigns/{campaignid}/listsandsegments.{xml|json}
Expected response: JSON XML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
 
{
    "Lists": [
        {
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "Name": "My List 1"
        },
        {
            "ListID": "b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2",
            "Name": "My List 2"
        }
    ],
    "Segments": [
        {
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "SegmentID": "c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3",
            "Title": "My Segment 1"
        },
        {
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "SegmentID": "d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4",
            "Title": "My Segment 2"
        }
    ]
}
Error responses:
Please see our response status codes documentation for details of potential error responses for any API request.

Campaign recipients

Retrieves a paged result representing all the subscribers that a given campaign was sent to. This includes their email address and the ID of the list they are a member of. You have complete control over how results should be returned including page size, sort order and sort direction.

GET https://api.createsend.com/api/v3.1/campaigns/{campaignid}/recipients.{xml|json}?page={pagenumber}&pagesize={pagesize}&orderfield={email|list}&orderdirection={asc|desc}

campaignid The ID of the campaign you want data for. Get the ID by getting sent campaigns.
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.
orderedirection 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": [
        {
            "EmailAddress": "example+1@example.com",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
        },
        {
            "EmailAddress": "example+2@example.com",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
        },
        {
            "EmailAddress": "example+3@example.com",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
        },
        {
            "EmailAddress": "example+4@example.com",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
        }
    ],
    "ResultsOrderedBy": "email",
    "OrderDirection": "asc",
    "PageNumber": 1,
    "PageSize": 1000,
    "RecordsOnThisPage": 4,
    "TotalNumberOfRecords": 4,
    "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.

Campaign bounces

Retrieves a paged result representing all the subscribers who bounced for a given campaign, and the type of bounce (Hard = Hard Bounce, Soft = Soft Bounce). You have complete control over how results should be returned including page size, sort order and sort direction.

GET https://api.createsend.com/api/v3.1/campaigns/{campaignid}/bounces.{xml|json}?date={YYYY-MM-DD HH:MM}&page={pagenumber}&pagesize={pagesize}&orderfield={email|list|date}&orderdirection={asc|desc}

campaignid The ID of the campaign you want data for. Get the ID by getting sent campaigns.
date Bounces on or after the date value specified will be returned. Must be in the format YYYY-MM-DD HH:MM. If not provided, results will not be filtered by date.
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.
orderedirection 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": [
        {
            "EmailAddress": "example+1@example.com",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "BounceType": "Hard",
            "Date": "2009-05-18 16:45:00",
            "Reason": "Invalid Email Address"
        },
        {
            "EmailAddress": "example+2@example.com",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "BounceType": "Hard",
            "Date": "2009-05-19 16:45:00",
            "Reason": "Hard Bounce"
        },
        {
            "EmailAddress": "example+3@example.com",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "BounceType": "Soft",
            "Date": "2009-05-20 16:45:00",
            "Reason": "Soft Bounce - Mailbox Full"
        },
        {
            "EmailAddress": "example+4@example.com",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "BounceType": "Soft",
            "Date": "2009-05-21 16:45:00",
            "Reason": "General Bounce"
        }
    ],
    "ResultsOrderedBy": "date",
    "OrderDirection": "asc",
    "PageNumber": 1,
    "PageSize": 1000,
    "RecordsOnThisPage": 4,
    "TotalNumberOfRecords": 4,
    "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:

  • 5: Invalid Date The date must be provided and in the format YYYY-MM-DD HH:MM
  • 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.

Campaign opens

Retrieves a paged result representing all subscribers who opened a given campaign, including the date/time and IP address from which they opened the campaign. When possible, the latitude, longitude, city, region, country code, and country name as geocoded from the IP address, are also returned. You have complete control over how results should be returned including page size, sort order and sort direction.

GET https://api.createsend.com/api/v3.1/campaigns/{campaignid}/opens.{xml|json}?date={YYYY-MM-DD HH:MM}&page={pagenumber}&pagesize={pagesize}&orderfield={email|list|date}&orderdirection={asc|desc}

campaignid The ID of the campaign you want data for. Get the ID by getting sent campaigns.
date Opens on or after the date value specified will be returned. Must be in the format YYYY-MM-DD HH:MM. If not provided, results will not be filtered by date.
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.
orderedirection 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": [
        {
            "EmailAddress": "example+1@example.com",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "Date": "2009-05-18 16:45:00",
            "IPAddress": "192.168.0.1",
            "Latitude": -33.8683,
            "Longitude": 151.2086,
            "City": "Sydney",
            "Region": "New South Wales",
            "CountryCode": "AU",
            "CountryName": "Australia"
        },
        {
            "EmailAddress": "example+2@example.com",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "Date": "2009-05-19 16:45:00",
            "IPAddress": "192.168.0.2",
            "Latitude": -33.8683,
            "Longitude": 151.2086,
            "City": "Sydney",
            "Region": "New South Wales",
            "CountryCode": "AU",
            "CountryName": "Australia"
        },
        {
            "EmailAddress": "example+3@example.com",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "Date": "2009-05-20 16:45:00",
            "IPAddress": "192.168.0.3",
            "Latitude": -33.8683,
            "Longitude": 151.2086,
            "City": "Sydney",
            "Region": "New South Wales",
            "CountryCode": "AU",
            "CountryName": "Australia"
        },
        {
            "EmailAddress": "example+4@example.com",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "Date": "2009-05-21 16:45:00",
            "IPAddress": "192.168.0.4",
            "Latitude": -33.8683,
            "Longitude": 151.2086,
            "City": "Sydney",
            "Region": "New South Wales",
            "CountryCode": "AU",
            "CountryName": "Australia"
        }
    ],
    "ResultsOrderedBy": "date",
    "OrderDirection": "asc",
    "PageNumber": 1,
    "PageSize": 1000,
    "RecordsOnThisPage": 4,
    "TotalNumberOfRecords": 4,
    "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:

  • 5: Invalid Date The date must be provided and in the format YYYY-MM-DD HH:MM
  • 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.

Campaign clicks

Retrieves a paged result representing all subscribers who clicked a link in a given campaign, including the date/time and IP address from which they clicked the link. When possible, the latitude, longitude, city, region, country code, and country name as geocoded from the IP address, are also returned. You have complete control over how results should be returned including page size, sort order and sort direction.

GET https://api.createsend.com/api/v3.1/campaigns/{campaignid}/clicks.{xml|json}?date={YYYY-MM-DD HH:MM}&page={pagenumber}&pagesize={pagesize}&orderfield={email|list|date}&orderdirection={asc|desc}

campaignid The ID of the campaign you want data for. Get the ID by getting sent campaigns.
date Clicks on or after the date value specified will be returned. Must be in the format YYYY-MM-DD HH:MM. If not provided, results will not be filtered by date.
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.
orderedirection 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": [
        {
            "EmailAddress": "example+1@example.com",
            "URL": "http://www.myexammple.com/index.html",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "Date": "2009-05-18 16:45:00",
            "IPAddress": "192.168.0.1",
            "Latitude": -33.8683,
            "Longitude": 151.2086,
            "City": "Sydney",
            "Region": "New South Wales",
            "CountryCode": "AU",
            "CountryName": "Australia"
        },
        {
            "EmailAddress": "example+1@example.com",
            "URL": "http://www.myexammple.com/homepage.html",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "Date": "2009-05-19 16:45:00",
            "IPAddress": "192.168.0.1",
            "Latitude": -33.8683,
            "Longitude": 151.2086,
            "City": "Sydney",
            "Region": "New South Wales",
            "CountryCode": "AU",
            "CountryName": "Australia"
        },
        {
            "EmailAddress": "example+2@example.com",
            "URL": "http://www.myexammple.com/index.html",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "Date": "2009-05-20 16:45:00",
            "IPAddress": "192.168.0.3",
            "Latitude": -33.8683,
            "Longitude": 151.2086,
            "City": "Sydney",
            "Region": "New South Wales",
            "CountryCode": "AU",
            "CountryName": "Australia"
        },
        {
            "EmailAddress": "example+3@example.com",
            "URL": "http://www.myexammple.com/index.html",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "Date": "2009-05-21 16:45:00",
            "IPAddress": "192.168.0.4",
            "Latitude": -33.8683,
            "Longitude": 151.2086,
            "City": "Sydney",
            "Region": "New South Wales",
            "CountryCode": "AU",
            "CountryName": "Australia"
        }
    ],
    "ResultsOrderedBy": "date",
    "OrderDirection": "asc",
    "PageNumber": 1,
    "PageSize": 1000,
    "RecordsOnThisPage": 4,
    "TotalNumberOfRecords": 4,
    "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:

  • 5: Invalid Date The date must be provided and in the format YYYY-MM-DD HH:MM
  • 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.

Campaign unsubscribes

Retrieves a paged result representing all subscribers who unsubscribed from the email for a given campaign, including the date/time and IP address they unsubscribed from. You have complete control over how results should be returned including page size, sort order and sort direction.

GET https://api.createsend.com/api/v3.1/campaigns/{campaignid}/unsubscribes.{xml|json}?date={YYYY-MM-DD HH:MM}&page={pagenumber}&pagesize={pagesize}&orderfield={email|list|date}&orderdirection={asc|desc}

campaignid The ID of the campaign you want data for. Get the ID by getting sent campaigns.
date Unsubscribes on or after the date value specified will be returned. Must be in the format YYYY-MM-DD HH:MM. If not provided, results will not be filtered by date.
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.
orderedirection 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": [
        {
            "EmailAddress": "example+1@example.com",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "Date": "2009-05-18 16:45:00",
            "IPAddress": "192.168.0.1"
        },
        {
            "EmailAddress": "example+1@example.com",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "Date": "2009-05-19 16:45:00",
            "IPAddress": "192.168.0.1"
        },
        {
            "EmailAddress": "example+2@example.com",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "Date": "2009-05-20 16:45:00",
            "IPAddress": "192.168.0.3"
        },
        {
            "EmailAddress": "example+3@example.com",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "Date": "2009-05-21 16:45:00",
            "IPAddress": "192.168.0.4"
        }
    ],
    "ResultsOrderedBy": "date",
    "OrderDirection": "asc",
    "PageNumber": 1,
    "PageSize": 1000,
    "RecordsOnThisPage": 4,
    "TotalNumberOfRecords": 4,
    "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:

  • 5: Invalid Date The date must be provided and in the format YYYY-MM-DD HH:MM
  • 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.

Campaign spam complaints

Retrieves a paged result representing all subscribers who marked the given campaign as spam, including the subscriber's list ID and the date/time they marked the campaign as spam. You have complete control over how results should be returned including page size, sort order and sort direction.

GET https://api.createsend.com/api/v3.1/campaigns/{campaignid}/spam.{xml|json}?date={YYYY-MM-DD HH:MM}&page={pagenumber}&pagesize={pagesize}&orderfield={email|list|date}&orderdirection={asc|desc}

campaignid The ID of the campaign you want data for. Get the ID by getting sent campaigns.
date Spam complaints on or after the date value specified will be returned. Must be in the format YYYY-MM-DD HH:MM. If not provided, results will not be filtered by date.
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.
orderedirection 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": [
        {
            "EmailAddress": "example+1@example.com",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "Date": "2009-05-18 16:45:00"
        },
        {
            "EmailAddress": "example+1@example.com",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "Date": "2009-05-19 16:45:00"
        },
        {
            "EmailAddress": "example+2@example.com",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "Date": "2009-05-20 16:45:00"
        },
        {
            "EmailAddress": "example+3@example.com",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "Date": "2009-05-21 16:45:00"
        }
    ],
    "ResultsOrderedBy": "date",
    "OrderDirection": "asc",
    "PageNumber": 1,
    "PageSize": 1000,
    "RecordsOnThisPage": 4,
    "TotalNumberOfRecords": 4,
    "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:

  • 5: Invalid Date The date must be provided and in the format YYYY-MM-DD HH:MM
  • 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.

Deleting a campaign

Deletes a campaign from your account. For draft and scheduled campaigns (prior to the time of scheduling), this will prevent the campaign from sending. If the campaign is already sent or in the process of sending, it will remove the campaign from the account.

campaignid The ID of the campaign to be deleted.

Delete https://api.createsend.com/api/v3.1/campaigns/{campaignid}.{xml|json}

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.

Unscheduling a campaign

Cancels the sending of the campaign and moves it back into the drafts. If the campaign is already sent or in the process of sending, this operation will fail.

campaignid The ID of the campaign to be unscheduled.

POST https://api.createsend.com/api/v3.1/campaigns/{campaignid}/unschedule.{xml|json}

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:

  • 341: Campaign is not scheduled The campaign is not currently scheduled. Either a schedule has not been specified or the campaign has already been sent (or is in the process of sending).

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

Create an account