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.

Segments

Segments allow you to create targeted sub-groups of subscribers based on conditions you set. The latest version of our API now lets you access the entire segment functionality from your own code.

Creating a segment

Post https://api.createsend.com/api/v3.3/segments/{listid}.{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.

Creates a new segment for a specific list. Please keep in mind that:

  1. The RuleGroups collection is optional. Individual RuleGroups can also be added incrementally.
  2. RuleGroups can be complicated. The full range of segment rules is available through the API, so we have provided more in-depth detail on segment rule construction. The example below creates a segment of any subscribers from ‘domain.com’ who subscribed at any point during the year 2009.
  • LISTID The ID of the list on which the segment should be created.
Expected request: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Title": "My Segment",
    "RuleGroups": [
        {
            "Rules": [
                {
                    "RuleType": "EmailAddress",
                    "Clause": "CONTAINS @domain.com"
                }
            ]
        },
        {
            "Rules": [
                {
                    "RuleType": "DateSubscribed",
                    "Clause": "AFTER 2009-01-01"
                },
                {
                    "RuleType": "DateSubscribed",
                    "Clause": "EQUALS 2009-01-01"
                }
            ]
        },
        {
            "Rules": [
                {
                    "RuleType": "DateSubscribed",
                    "Clause": "BEFORE 2010-01-01"
                }
            ]
        }
    ]
}

Response

Contains the ID of the segment which has been created.

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

"a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1"

Invalid Rules Error Responses

When there is a problem parsing the Rules, the Result will contain an additional element, called ResultData, which will be a collection of RuleResult objects. This will assist in determining the nature of the problem and reconstructing a better ruleset.

Every Rule in the original Rules collections will have a matching RuleResult in this collection, containing the following elements:

Code The result code for this Rule.

Message An explanatory message for this result code.

RuleType The original RuleType, for debugging and matching purposes.

ClauseResults A collection of items, each of type ClauseResult, one for each Clause in the original Clauses collection in the matching Rule. Each ClauseResult consists of the following elements:

  • Code The result code for this Clause.
  • Message An explanatory message for this result code.
  • Clause The original clause, for matching and debugging.

A wide variety of parsing errors are possible. The full range of possible result Codes are explained following the example response.

In addition to the basic error responses, a large number of codes can be presented as part of a RuleResult or ClauseResult as a result of parsing the supplied Rules collection.

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

  • 273: Segment Title Empty The segment title cannot be empty.
  • 275: Duplicate Segment Title The segment title must be unique in a list.
  • 277: Invalid Segment Rules One or more of the supplied Rules could not be parsed. Check the ResultData object for more detail.
  • 283: Segment Limits Reached You’ve reached your API segment limit. To create additional segments or segment rules, please contact customer support.
POSSIBLE CODES WHICH COULD APPEAR AS PART OF A RULERESULT:
  • 2703: Invalid Segment Clauses At least one of the Clauses in this Rule could not be parsed. Check the ClauseResults for details.
  • 2704: Empty Segment RuleType RuleType cannot be empty
  • 2705: Invalid Segment RuleType RuleType must be one of "Name", "EmailAddress", "DateSubscribed", "CampaignOpened", "CampaignClickedAny", "CampaignClickedSpecific", "CampaignNotClickedSpecific", "CampaignOpenedNoClick", "CampaignNotOpened", or the personalisation tag of any custom field on the list.
  • 2706: Empty Segment Clauses Any segment rule must have at least one clause
POSSIBLE CODES WHICH COULD APPEAR AS PART OF A CLAUSERESULT:
  • 2710: Empty Clause A clause cannot be empty.
  • 2712: Invalid Verb For Name Rule The verb supplied is illegal for a Name-based rule. Consult the documentation.
  • 2713: Invalid Verb For Email Rule The verb supplied is illegal for a Email-based rule. Consult the documentation.
  • 2714: Invalid Verb For DateSubscribed Rule The verb supplied is illegal for a DateSubscribed-based rule. Consult the documentation.
  • 2715: Invalid Verb For Text Field Rule The verb supplied is illegal for a rule based on a Text custom field. Consult the documentation.
  • 2716: Invalid Verb For Number Field Rule The verb supplied is illegal for a rule based on a Number custom field. Consult the documentation.
  • 2717: Invalid Verb For Multi-Option Field Rule The verb supplied is illegal for a rule based on a Multi-Option custom field. Consult the documentation.
  • 2718: Invalid Verb For Date Field Rule The verb supplied is illegal for a rule based on a Date custom field. Consult the documentation.
  • 2719: Required Clause Object Missing The verb used requires a matching object to be part of the clause.
  • 2720: Invalid Date Format All dates must be supplied in the format yyyy-mm-dd.
  • 2721: Invalid Number Format Objects supplied in a number-based clause must be parsable as a number.
  • 2722: Option Doesnt Exist For Field The object supplied is not a valid option on the custom field the rule is based upon.
  • 2723: Invalid year for Date Subscribed An operand supplied as part of a DateSubscribed-based clause can only be from the last ten (10) years, including the current year.
  • 2750: Valid CampaignID Required The campaign ID supplied must be a fully-formed API CampaignID.
  • 2751: Campaign Not Sent To List The CampaignID supplied has never been sent to this list or any segment of it.
  • 2753: Link Not In Campaign The url given was not a clickable link in the campaign matching the CampaignID supplied.
  • 2754: Segment Rule Clause Not Parsed Clause not parsed due to invalid RuleType.
  • 2755: Invalid Between Date Format Between date range must be in the format 'YYYY-MM-DD AND YYYY-MM-DD'.
  • 2756: Invalid Between Number Format Between number range must be in the format 'X AND Y'.
  • 2757: Invalid Verb For Location Rule The verb supplied is illegal for a Location-based rule. Consult the documentation.
  • 2758: Invalid Operand For Location Rule The operand supplied is illegal for a Location-based rule. Consult the documentation.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Code": 277,
    "Message": "The supplied segment rules have some problems",
    "ResultData": [
        {
            "RuleType": "CampaignOpened",
            "ClauseResult": {
                "Clause": "AFTER 2010-01-01",
                "Code": 2750,
                "Message": "Rule requires a valid API CampaignID"
            },
            "Code": 2703,
            "Message": "The supplied clauses have some problems"
        },
        {
            "RuleType": "FavouriteAnimal",
            "ClauseResult": {
                "Clause": "EQUALS Three-Toed Sloth",
                "Code": 0,
                "Message": "Success"
            },
            "Code": 0,
            "Message": "Success"
        },
        {
            "RuleType": "Name",
            "ClauseResult": {
                "Clause": "EQUALS Gertrude Gainforth",
                "Code": 0,
                "Message": "Success"
            },
            "Code": 0,
            "Message": "Success"
        },
        {
            "RuleType": "Name",
            "ClauseResult": {
                "Clause": "CONTAINS President",
                "Code": 2712,
                "Message": "Verb is illegal for Name-based rules"
            },
            "Code": 2703,
            "Message": "The supplied clauses have some problems"
        },
        {
            "RuleType": "BustedCustard",
            "ClauseResult": {
                "Clause": "EQUALS yes",
                "Code": 2754,
                "Message": "Clause not parsed due to invalid RuleType"
            },
            "Code": 2705,
            "Message": "RuleType must be one of Name|EmailAddress|DateSubscribed|Campaign(Opened(NoClick)?|Clicked(Any|Specific)|NotOpened) or a valid custom field personalisation tag"
        }
    ]
}

Updating a segment

Put https://api.createsend.com/api/v3.3/segments/{segmentid}.{xml|json}

Updates the name of an existing segment and optionally overwrite any existing segment rules with new rules.

  1. Updating a segment will always attempt to change the Title, which is compulsory.
  2. The Rules collection is optional when updating. If it is present, all existing rules will be deleted before parsing the new ones. If it is not present, existing rules will remain unchanged.
  • SEGMENTID The ID of the segment to be updated.
Expected request: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Title": "My Segment",
    "RuleGroups": [
        {
            "Rules": [
                {
                    "RuleType": "EmailAddress",
                    "Clause": "CONTAINS @domain.com"
                }
            ]
        },
        {
            "Rules": [
                {
                    "RuleType": "DateSubscribed",
                    "Clause": "AFTER 2009-01-01"
                },
                {
                    "RuleType": "DateSubscribed",
                    "Clause": "EQUALS 2009-01-01"
                }
            ]
        },
        {
            "Rules": [
                {
                    "RuleType": "DateSubscribed",
                    "Clause": "BEFORE 2010-01-01"
                }
            ]
        }
    ]
}
Expected response: (Same for all languages)
HTTP/1.1 200 OK

Invalid Rules Error Responses

When there is a problem parsing the Rules, the Result will contain an additional element, called ResultData, which will be a collection of RuleResult objects. This will assist in determining the nature of the problem and reconstructing a better ruleset.

Every Rule in the original Rules collections will have a matching RuleResult in this collection, containing the following elements:

Code The result code for this Rule.

Message An explanatory message for this result code.

RuleType The original RuleType, for debugging and matching purposes.

ClauseResults A collection of items, each of type ClauseResult, one for each Clause in the original Clauses collection in the matching Rule. Each ClauseResult consists of the following elements:

  • Code The result code for this Clause.
  • Message An explanatory message for this result code.
  • Clause The original clause, for matching and debugging.

A wide variety of parsing errors are possible. The full range of possible result Codes are explained following the example response.

In addition to the basic error responses, a large number of codes can be presented as part of a RuleResult or ClauseResult as a result of parsing the supplied Rules collection.

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

  • 271: Invalid SegmentID Invalid SegmentID or the Segment doesn't exist
  • 272: Segment Has Campaigns A segment attached to unsent campaign drafts cannot be deleted
  • 273: Segment Title Empty The segment title cannot be empty.
  • 275: Duplicate Segment Title The segment title must be unique in a list.
  • 277: Invalid Segment Rules One or more of the supplied Rules could not be parsed. Check the ResultData object for more detail.
  • 278: Segment calculation is in progress Segment calculation is in progress. Please try again later.
  • 283: Segment Limits Reached You’ve reached your API segment limit. To create additional segments or segment rules, please contact customer support.
  • 284: This is a system segment and it cannot be modified You've tried to modify or delete an engagement segment. These are provided by default and can't be changed.
POSSIBLE CODES WHICH COULD APPEAR AS PART OF A RULERESULT:
  • 2703: Invalid Segment Clauses At least one of the Clauses in this Rule could not be parsed. Check the ClauseResults for details.
  • 2704: Empty Segment RuleType RuleType cannot be empty
  • 2705: Invalid Segment RuleType RuleType must be one of "Name", "EmailAddress", "DateSubscribed", "CampaignOpened", "CampaignClickedAny", "CampaignClickedSpecific", "CampaignNotClickedSpecific", "CampaignOpenedNoClick", "CampaignNotOpened", or the personalisation tag of any custom field on the list.
  • 2706: Empty Segment Clauses Any segment rule must have at least one clause
POSSIBLE CODES WHICH COULD APPEAR AS PART OF A CLAUSERESULT:
  • 2710: Empty Clause A clause cannot be empty.
  • 2712: Invalid Verb For Name Rule The verb supplied is illegal for a Name-based rule. Consult the documentation.
  • 2713: Invalid Verb For Email Rule The verb supplied is illegal for a Email-based rule. Consult the documentation.
  • 2714: Invalid Verb For DateSubscribed Rule The verb supplied is illegal for a DateSubscribed-based rule. Consult the documentation.
  • 2715: Invalid Verb For Text Field Rule The verb supplied is illegal for a rule based on a Text custom field. Consult the documentation.
  • 2716: Invalid Verb For Number Field Rule The verb supplied is illegal for a rule based on a Number custom field. Consult the documentation.
  • 2717: Invalid Verb For Multi-Option Field Rule The verb supplied is illegal for a rule based on a Multi-Option custom field. Consult the documentation.
  • 2718: Invalid Verb For Date Field Rule The verb supplied is illegal for a rule based on a Date custom field. Consult the documentation.
  • 2719: Required Clause Object Missing The verb used requires a matching object to be part of the clause.
  • 2720: Invalid Date Format All dates must be supplied in the format yyyy-mm-dd.
  • 2721: Invalid Number Format Objects supplied in a number-based clause must be parsable as a number.
  • 2722: Option Doesnt Exist For Field The object supplied is not a valid option on the custom field the rule is based upon.
  • 2723: Invalid year for Date Subscribed An operand supplied as part of a DateSubscribed-based clause can only be from the last ten (10) years, including the current year.
  • 2750: Valid CampaignID Required The campaign ID supplied must be a fully-formed API CampaignID.
  • 2751: Campaign Not Sent To List The CampaignID supplied has never been sent to this list or any segment of it.
  • 2753: Link Not In Campaign The url given was not a clickable link in the campaign matching the CampaignID supplied.
  • 2754: Segment Rule Clause Not Parsed Clause not parsed due to invalid RuleType.
  • 2755: Invalid Between Date Format Between date range must be in the format 'YYYY-MM-DD AND YYYY-MM-DD'.
  • 2756: Invalid Between Number Format Between number range must be in the format 'X AND Y'.
  • 2757: Invalid Verb For Location Rule The verb supplied is illegal for a Location-based rule. Consult the documentation.
  • 2758: Invalid Operand For Location Rule The operand supplied is illegal for a Location-based rule. Consult the documentation.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Code": 277,
    "Message": "The supplied segment rules have some problems",
    "ResultData": [
        {
            "RuleType": "CampaignOpened",
            "ClauseResult": {
                "Clause": "AFTER 2010-01-01",
                "Code": 2750,
                "Message": "Rule requires a valid API CampaignID"
            },
            "Code": 2703,
            "Message": "The supplied clauses have some problems"
        },
        {
            "RuleType": "FavouriteAnimal",
            "ClauseResult": {
                "Clause": "EQUALS Three-Toed Sloth",
                "Code": 0,
                "Message": "Success"
            },
            "Code": 0,
            "Message": "Success"
        },
        {
            "RuleType": "Name",
            "ClauseResult": {
                "Clause": "EQUALS Gertrude Gainforth",
                "Code": 0,
                "Message": "Success"
            },
            "Code": 0,
            "Message": "Success"
        },
        {
            "RuleType": "Name",
            "ClauseResult": {
                "Clause": "CONTAINS President",
                "Code": 2712,
                "Message": "Verb is illegal for Name-based rules"
            },
            "Code": 2703,
            "Message": "The supplied clauses have some problems"
        },
        {
            "RuleType": "BustedCustard",
            "ClauseResult": {
                "Clause": "EQUALS yes",
                "Code": 2754,
                "Message": "Clause not parsed due to invalid RuleType"
            },
            "Code": 2705,
            "Message": "RuleType must be one of Name|EmailAddress|DateSubscribed|Campaign(Opened(NoClick)?|Clicked(Any|Specific)|NotOpened) or a valid custom field personalisation tag"
        }
    ]
}

Adding a segment rulegroup

Post https://api.createsend.com/api/v3.3/segments/{segmentid}/rules.{xml|json}

Adds a new rulegroup to an existing segment. Adding a RuleGroup will not remove any existing rulegroups on the segment, but simply add an additional requirement for membership.

  • SEGMENTID The ID of the segment to which the rule will be added.
Expected request: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Rules": [
        {
            "RuleType": "Name",
            "Clause": "NOT_PROVIDED"
        },
        {
            "RuleType": "Name",
            "Clause": "EQUALS Subscriber Name"
        },
    ]
}
Expected response: (Same for all languages)
HTTP/1.1 200 OK

Invalid Rules Error Responses

When there is a problem parsing the Rules, the Result will contain an additional element, called ResultData, which will be a collection of RuleResult objects. This will assist in determining the nature of the problem and reconstructing a better ruleset.

Every Rule in the original Rules collections will have a matching RuleResult in this collection, containing the following elements:

Code The result code for this Rule.

Message An explanatory message for this result code.

RuleType The original RuleType, for debugging and matching purposes.

ClauseResults A collection of items, each of type ClauseResult, one for each Clause in the original Clauses collection in the matching Rule. Each ClauseResult consists of the following elements:

  • Code The result code for this Clause.
  • Message An explanatory message for this result code.
  • Clause The original clause, for matching and debugging.

A wide variety of parsing errors are possible. The full range of possible result Codes are explained following the example response.

In addition to the basic error responses, a large number of codes can be presented as part of a RuleResult or ClauseResult as a result of parsing the supplied Rules collection.

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

  • 271: Invalid SegmentID Invalid SegmentID or the Segment doesn't exist
  • 277: Invalid Segment Rules One or more of the supplied Rules could not be parsed. Check the ResultData object for more detail.
  • 283: Segment Limits Reached You’ve reached your API segment limit. To create additional segments or segment rules, please contact customer support.
  • 284: This is a system segment and it cannot be modified You've tried to modify or delete an engagement segment. These are provided by default and can't be changed.
POSSIBLE CODES WHICH COULD APPEAR AS PART OF A RULERESULT:
  • 2703: Invalid Segment Clauses At least one of the Clauses in this Rule could not be parsed. Check the ClauseResults for details.
  • 2704: Empty Segment RuleType RuleType cannot be empty
  • 2705: Invalid Segment RuleType RuleType must be one of "Name", "EmailAddress", "DateSubscribed", "CampaignOpened", "CampaignClickedAny", "CampaignClickedSpecific", "CampaignNotClickedSpecific", "CampaignOpenedNoClick", "CampaignNotOpened", or the personalisation tag of any custom field on the list.
  • 2706: Empty Segment Clauses Any segment rule must have at least one clause
POSSIBLE CODES WHICH COULD APPEAR AS PART OF A CLAUSERESULT:
  • 2710: Empty Clause A clause cannot be empty.
  • 2712: Invalid Verb For Name Rule The verb supplied is illegal for a Name-based rule. Consult the documentation.
  • 2713: Invalid Verb For Email Rule The verb supplied is illegal for a Email-based rule. Consult the documentation.
  • 2714: Invalid Verb For DateSubscribed Rule The verb supplied is illegal for a DateSubscribed-based rule. Consult the documentation.
  • 2715: Invalid Verb For Text Field Rule The verb supplied is illegal for a rule based on a Text custom field. Consult the documentation.
  • 2716: Invalid Verb For Number Field Rule The verb supplied is illegal for a rule based on a Number custom field. Consult the documentation.
  • 2717: Invalid Verb For Multi-Option Field Rule The verb supplied is illegal for a rule based on a Multi-Option custom field. Consult the documentation.
  • 2718: Invalid Verb For Date Field Rule The verb supplied is illegal for a rule based on a Date custom field. Consult the documentation.
  • 2719: Required Clause Object Missing The verb used requires a matching object to be part of the clause.
  • 2720: Invalid Date Format All dates must be supplied in the format yyyy-mm-dd.
  • 2721: Invalid Number Format Objects supplied in a number-based clause must be parsable as a number.
  • 2722: Option Doesnt Exist For Field The object supplied is not a valid option on the custom field the rule is based upon.
  • 2723: Invalid year for Date Subscribed An operand supplied as part of a DateSubscribed-based clause can only be from the last ten (10) years, including the current year.
  • 2750: Valid CampaignID Required The campaign ID supplied must be a fully-formed API CampaignID.
  • 2751: Campaign Not Sent To List The CampaignID supplied has never been sent to this list or any segment of it.
  • 2753: Link Not In Campaign The url given was not a clickable link in the campaign matching the CampaignID supplied.
  • 2754: Segment Rule Clause Not Parsed Clause not parsed due to invalid RuleType.
  • 2755: Invalid Between Date Format Between date range must be in the format 'YYYY-MM-DD AND YYYY-MM-DD'.
  • 2756: Invalid Between Number Format Between number range must be in the format 'X AND Y'.
  • 2757: Invalid Verb For Location Rule The verb supplied is illegal for a Location-based rule. Consult the documentation.
  • 2758: Invalid Operand For Location Rule The operand supplied is illegal for a Location-based rule. Consult the documentation.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Code": 277,
    "Message": "The supplied segment rules have some problems",
    "ResultData": [
        {
            "RuleType": "CampaignOpened",
            "ClauseResult": {
                "Clause": "AFTER 2010-01-01",
                "Code": 2750,
                "Message": "Rule requires a valid API CampaignID"
            },
            "Code": 2703,
            "Message": "The supplied clauses have some problems"
        },
        {
            "RuleType": "FavouriteAnimal",
            "ClauseResult": {
                "Clause": "EQUALS Three-Toed Sloth",
                "Code": 0,
                "Message": "Success"
            },
            "Code": 0,
            "Message": "Success"
        },
        {
            "RuleType": "Name",
            "ClauseResult": {
                "Clause": "EQUALS Gertrude Gainforth",
                "Code": 0,
                "Message": "Success"
            },
            "Code": 0,
            "Message": "Success"
        },
        {
            "RuleType": "Name",
            "ClauseResult": {
                "Clause": "CONTAINS President",
                "Code": 2712,
                "Message": "Verb is illegal for Name-based rules"
            },
            "Code": 2703,
            "Message": "The supplied clauses have some problems"
        },
        {
            "RuleType": "BustedCustard",
            "ClauseResult": {
                "Clause": "EQUALS yes",
                "Code": 2754,
                "Message": "Clause not parsed due to invalid RuleType"
            },
            "Code": 2705,
            "Message": "RuleType must be one of Name|EmailAddress|DateSubscribed|Campaign(Opened(NoClick)?|Clicked(Any|Specific)|NotOpened) or a valid custom field personalisation tag"
        }
    ]
}

Getting a segment’s details

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

Returns the name, list ID, segment ID and number of active subscribers within an existing segment as well as the current rules for that segment.

  • segmentId The ID of the segment to which the rule will be added
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "ActiveSubscribers": 0,
    "RuleGroups": [
        {
            "Rules": [
                {
                    "RuleType": "Subject1_1",
                    "Clause": "Clause1_1"
                },
                {
                    "RuleType": "Subject1_2",
                    "Clause": "Clause1_2"
                }
            ]
        },
        {
            "Rules": [
                {
                    "RuleType": "Subject2_1",
                    "Clause": "Clause2_1"
                }
            ]
        }
    ],
    "ListID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
    "SegmentID": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
    "Title": "Segment Title"
}
Error responses:

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

  • 271: Invalid SegmentID Invalid SegmentID or the Segment doesn't exist

Deleting a segment

Delete https://api.createsend.com/api/v3.3/segments/{segmentid}.{xml|json}

Deletes an existing segment from a subscriber list.

  • segmentId The ID of the segment 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:

  • 271: Invalid SegmentID Invalid SegmentID or the Segment doesn't exist
  • 272: Segment Has Campaigns A segment attached to unsent campaign drafts cannot be deleted
  • 284: This is a system segment and it cannot be modified You've tried to modify or delete an engagement segment. These are provided by default and can't be changed.

Deleting a segment’s rules

Delete https://api.createsend.com/api/v3.3/segments/{segmentid}/rules.{xml|json}

Clears out any existing rules (and parent rulegroups) for a current segment, basically creating a blank slate where new rules can be added.

  • segmentid The ID of the segment whose rules are 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.

  • 271: Invalid SegmentID Invalid SegmentID or the Segment doesn't exist
  • 284: This is a system segment and it cannot be modified You've tried to modify or delete an engagement segment. These are provided by default and can't be changed.

How to work with the segment rules

How segment membership works

Membership of a list segment is decided on the basis of a collection of RuleGroups and the Rules within them. The rules within a rulegroup are joined together by means of a logical OR. The rulegroups are joined together by means of a logical AND, so that any subscriber who satisfies at least one of the rules in every rulegroup is a member of the segment.

Rules themselves consist of a RuleType, and a collection of Clauses which will operate on that RuleType. A Clause is simply a string which consists of an operating Verb and in most cases an Object (or operand).

The RuleGroup collection

A rulegroup collection is used as part of the input when creating, updating, or part of the output getting the details of a segment.

When adding a rulegroup to a segment the structure is similar, except only one rulegroup is added to the existing collection (which isn’t part of the input).

There is no requirement that the RuleType in each Rule be unique.

Example rule collection:JSONXML
"RuleGroups": [
    {
        "Rules": [
            {
                "RuleType": "EmailAddress",
                "Clause": "CONTAINS @domain.com"
            }
        ]
    },
    {
        "Rules": [
            {
                "RuleType": "DateSubscribed",
                "Clause": "AFTER 2009-01-01"
            },
            {
                "RuleType": "DateSubscribed",
                "Clause": "EQUALS 2009-01-01"
            }
        ]
    },
    {
        "Rules": [
            {
                "RuleType": "DateSubscribed",
                "Clause": "BEFORE 2010-01-01"
            }
        ]
    },
    {
        "Rules": [
            {
                "RuleType": "[Frequency]",
                "Clause": "NOT_EQUALS Emergency Only"
            }
        ]
    },
    {
        "Rules": [
            {
                "RuleType": "CampaignOpened",
                "Clause": "1234123412341234"
            },
            {
                "RuleType": "CampaignOpened",
                "Clause": "abcdabcdabcdabcd"
            }
        ]
    }
]

Interpreting the rules

In the collection above we have five rulegroups:

  1. A RuleType of EmailAddress means we are filtering subscribers on the basis of their email address. The segment will pick up only subscribers whose email contains “@domain.com”
  2. DateSubscribed means filtering on the of the list member’s subscription date. Two rules in this rulegroup, meaning a subscriber needs to have a date either AFTER or ON January 1st 2009.
  3. The third rulegroup also filters on DateSubscribed, requiring that the subscription date be before January 1st 2010.
  4. Then we filter on the [Frequency] custom field, picking only those subscribers not registered to “Emergency Only” communications.
  5. Finally, using CampaignOpened means we filter on whether or not they opened particular campaigns. Two rules with two campaign IDs are provided, so an open on either will mean the subscriber satisfies this rule.

A subscriber is therefore a member of this segment providing:

  1. Their email address contains “@domain.com”
  2. AND they subscribed on 1st January 2009
    OR after 1st January 2009
  3. AND they subscribed before 1st January 2009
  4. AND their frequency custom field is not equal to “Emergency Only”
  5. AND they opened one of the following campaigns: 1234123412341234
    OR abcdabcdabcdabcd

Getting active subscribers

Get https://api.createsend.com/api/v3.3/segments/{segmentid}/active.{xml|json}?date={YYYY-MM-DD}&page={pagenumber}&pagesize={pagesize}&orderfield={email|name|date}&orderdirection={asc|desc}&includetrackingpreference={true|false}

Returns all of the active subscribers that match the rules for a specific segment. This includes their name, email address, any custom fields and the date they subscribed. You have complete control over how results should be returned including page sizes, sort order and sort direction.

  • SegmentID The ID of the segment you want the active subscribers for.
  • Date Subscribers which became active on or after the date value specified will be returned. Must be in the format YYYY-MM-DD. 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: date.
  • OrderDirection The direction in which results should be ordered. Default: asc.
  • IncludeTrackingPreference Include subscriber consent to track values. Default: false.
Expected response: JSONXML
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Results": [
        {
            "EmailAddress": "[email protected]",
            "Name": "Person One",
            "ListJoinedDate": "2021-10-25 10:28:00",
            "Date": "2021-10-25 10:28:00",
            "State": "Active",
            "CustomFields": [
                {
                    "Key": "website",
                    "Value": "https://example.com"
                },
                {
                    "Key": "age",
                    "Value": "24"
                },
                {
                    "Key": "subscription date",
                    "Value": "2021-03-09"
                }
            ],
            "ConsentToTrack": "Yes"
        },
        {
            "EmailAddress": "[email protected]",
            "Name": "Person Two",
            "ListJoinedDate": "2021-10-25 12:17:00",
            "Date": "2021-10-25 12:17:00",            
            "State": "Active",
            "CustomFields": [
                {
                    "Key": "website",
                    "Value": "https://subdomain.example.com"
                }
            ],
            "ConsentToTrack": ""
        },
        {
            "EmailAddress": "[email protected]",
            "Name": "Person Three",
            "ListJoinedDate": "2021-10-25 12:52:00",
            "Date": "2021-10-25 12:52:00",
            "State": "Active",
            "CustomFields": [
                {
                    "Key": "website",
                    "Value": "https://subdomain.example.com"
                }
            ],
            "ConsentToTrack": "No"
        },
        {
            "EmailAddress": "[email protected]",
            "Name": "Person Four",
            "ListJoinedDate": "2021-10-27 13:13:00",
            "Date": "2021-10-27 13:13:00",            
            "State": "Active",
            "CustomFields": [],
            "ConsentToTrack": "No"
        },
        {
            "EmailAddress": "[email protected]",
            "Name": "Person Five",
            "ListJoinedDate": "2021-10-27 13:13:00",
            "Date": "2021-10-27 13:13:00",            
            "State": "Active",
            "CustomFields": [],
            "ConsentToTrack": "Yes"
        }
    ],
    "ResultsOrderedBy": "email",
    "OrderDirection": "asc",
    "PageNumber": 1,
    "PageSize": 1000,
    "RecordsOnThisPage": 5,
    "TotalNumberOfRecords": 5,
    "NumberOfPages": 1
}
Error responses:

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

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

  • 5: Invalid Date The Send Date provided was invalid.
  • 271: Invalid SegmentID Invalid SegmentID or the Segment doesn't exist
  • 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.