Campaign management - API documentation | Campaign Monitor

Our API

The Campaign Monitor API opens up a world of possibilities for integrating our platform with your favorite CMS, blog, or other third party software.

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

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

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. The InlineCss field controls whether all CSS should be moved inline for the HTML component. This field is optional and defaults to true if not provided.

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.

If you are using the SegmentIDs section, remove the ListIDs section from your request.

  • ClientID The ID of the client for whom the campaign should be created. You can get this ID by getting your clients.
Expected request: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Name": "My Campaign Name",
    "Subject": "My Subject",
    "FromName": "My Name",
    "FromEmail": "[email protected]",
    "ReplyTo": "[email protected]",
    "HtmlUrl": "http://example.com/campaigncontent/index.html",
    "ListIDs": [
        "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
        "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1"
    ],
    "SegmentIDs": [
        "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
        "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1"
    ],
    "InlineCss": true
}
  • InlineCss Optional. Enable/disable moving all CSS inline. Valid values are true or false. Defaults to true if not provided.
Expected response: JSONXML
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.
  • 322: From Name Contains Reserved Personalization Tag From name can not include personalization tags other than custom fields
  • 323: From Email Address Requires a Fallback From email address requires a fallback: [customfield, [email protected]]
  • 324: From Address Contains Reserved Personalization Tag From email address can not include personalization tags other than custom fields
  • 325: Reply-To Address Requires a Fallback Reply-to address requires a fallback: [customfield, [email protected]]
  • 326: Reply-To Address Uses Reserved Personalization Tag Reply-to address can not include personalization tags other than custom fields
  • 4201: Contains Flash Flash is not supported by almost every email client out there and should not be included in your emails.
  • 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.
  • 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.
  • 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.

Creating a campaign from a template

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

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.

Note: Creating a campaign from an email builder template is currently not supported.

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

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 request: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "Name": "My Campaign Name",
  "Subject": "My Subject",
  "FromName": "My Name",
  "FromEmail": "[email protected]",
  "ReplyTo": "[email protected]",
  "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/"
              }
            ]
          }
        ]
      }
    ]
  }
}
  • Singlelines Represents 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.
  • Multilines Represents content for floating multiline tags. Each entry should contain:
    • Content The content to populate the multiline tag in the template.
  • Images Represents 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.
  • Repeaters Represents 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: JSONXML
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="https://example.com/">This is a heading</a></p>
    <div><p>This is example</p><p>multiline <a href="https://example.com/">content</a>...</p></div>
    <a href="https://example.com/"><img id="header-image" width="500" src="https://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="https://example.com/">This is a repeater heading</a></p>
      <div><p>This is example</p><p>multiline <a href="https://example.com/">content</a>...</p></div>
      <a href="https://example.com/"><img width="500" src="https://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="https://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.
  • 322: From Name Contains Reserved Personalization Tag From name can not include personalization tags other than custom fields
  • 323: From Email Address Requires a Fallback From email address requires a fallback: [customfield, [email protected]]
  • 324: From Address Contains Reserved Personalization Tag From email address can not include personalization tags other than custom fields
  • 325: Reply-To Address Requires a Fallback Reply-to address requires a fallback: [customfield, [email protected]]
  • 4001: Invalid Template ID Invalid Template ID, or the template doesn't exist or belong to the client.

Sending a draft campaign

Post https://api.createsend.com/api/v3.3/campaigns/{campaignid}/send.{xml|json}

Please note: When sending to segments, to ensure they have finished calculating, we recommend waiting approximately one hour after importing subscribers, creating segments, or updating segment rules.

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.
Expected request: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "ConfirmationEmail": "[email protected], [email protected]",
    "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: (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:

  • 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) and campaign previews. 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

Post https://api.createsend.com/api/v3.3/campaigns/{campaignid}/sendpreview.{xml|json}

Send a preview of any draft campaign to a number of email addresses you specify. Any personalization tags in your draft campaign will be populated using fallback values.

  • 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.
Expected request: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "PreviewRecipients": ["[email protected]", "[email protected]"]
}
  • PreviewRecipients A collection of intended recipients of the campaign preview.
  • Personalize Deprecated parameter. All values passed to this field will be ignored and personalization will be displayed using fallbacks.
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:

  • 333: No Test Campaigns Available Each customer can send a limited number of test campaigns (of less than 6 recipients) and campaign previews. 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>
  • 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 email client usage

Get https://api.createsend.com/api/v3.3/campaigns/{campaignid}/emailclientusage.{xml|json}

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.
Expected response: JSONXML
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

Get https://api.createsend.com/api/v3.3/campaigns/{campaignid}/listsandsegments.{xml|json}

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.
Expected response: JSONXML
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

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

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.

  • 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.
  • Orderdirection The direction in which results should be ordered. Default: asc.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Results": [
        {
            "EmailAddress": "[email protected]",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
        },
        {
            "EmailAddress": "[email protected]",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
        },
        {
            "EmailAddress": "[email protected]",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
        },
        {
            "EmailAddress": "[email protected]",
            "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

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

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.

  • 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.
  • Orderdirection The direction in which results should be ordered. Default: asc.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Results": [
        {
            "EmailAddress": "[email protected]",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "BounceType": "Hard",
            "Date": "2009-05-18 16:45:00",
            "Reason": "Invalid Email Address"
        },
        {
            "EmailAddress": "[email protected]",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "BounceType": "Hard",
            "Date": "2009-05-19 16:45:00",
            "Reason": "Hard Bounce"
        },
        {
            "EmailAddress": "[email protected]",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "BounceType": "Soft",
            "Date": "2009-05-20 16:45:00",
            "Reason": "Soft Bounce - Mailbox Full"
        },
        {
            "EmailAddress": "[email protected]",
            "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 Send Date provided was invalid.
  • 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

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

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.

  • 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.
  • Orderdirection The direction in which results should be ordered. Default: asc.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Results": [
        {
            "EmailAddress": "[email protected]",
            "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": "[email protected]",
            "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": "[email protected]",
            "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": "[email protected]",
            "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 Send Date provided was invalid.
  • 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

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

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.

  • 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.
  • Orderdirection The direction in which results should be ordered. Default: asc.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Results": [
        {
            "EmailAddress": "[email protected]",
            "URL": "https://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": "[email protected]",
            "URL": "https://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": "[email protected]",
            "URL": "https://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": "[email protected]",
            "URL": "https://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 Send Date provided was invalid.
  • 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

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

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.

  • 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.
  • Orderdirection The direction in which results should be ordered. Default: asc.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Results": [
        {
            "EmailAddress": "[email protected]",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "Date": "2009-05-18 16:45:00",
            "IPAddress": "192.168.0.1"
        },
        {
            "EmailAddress": "[email protected]",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "Date": "2009-05-19 16:45:00",
            "IPAddress": "192.168.0.1"
        },
        {
            "EmailAddress": "[email protected]",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "Date": "2009-05-20 16:45:00",
            "IPAddress": "192.168.0.3"
        },
        {
            "EmailAddress": "[email protected]",
            "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 Send Date provided was invalid.
  • 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

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

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.

  • 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.
  • Orderdirection The direction in which results should be ordered. Default: asc.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Results": [
        {
            "EmailAddress": "[email protected]",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "Date": "2009-05-18 16:45:00"
        },
        {
            "EmailAddress": "[email protected]",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "Date": "2009-05-19 16:45:00"
        },
        {
            "EmailAddress": "[email protected]",
            "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
            "Date": "2009-05-20 16:45:00"
        },
        {
            "EmailAddress": "[email protected]",
            "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 Send Date provided was invalid.
  • 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

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

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

Unscheduling a campaign

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

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

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

Campaign Summary

Get https://api.createsend.com/api/v3.3/campaigns/{campaignid}/summary.{xml|json}

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

  • CampaignID The ID of the campaign you want data for. Get the ID by getting sent campaigns.
Expected response: JSONXML
HTTP/1.1 200 OK

{
    "Name": "Warehouse sale",
    "Recipients": 1000,
    "TotalOpened": 345,
    "Clicks": 132,
    "Unsubscribed": 43,
    "Bounced": 15,
    "UniqueOpened": 298,
    "SpamComplaints": 23,
    "WebVersionURL": "https://createsend.com/t/y-A1A1A1A1A1A1A1A1A1A1A1A1/",
    "WebVersionTextURL": "https://createsend.com/t/y-A1A1A1A1A1A1A1A1A1A1A1A1/t",
    "WorldviewURL": "https://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.