Our API

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

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.

POST https://api.createsend.com/api/v3.1/segments/{listid}.{xml|json}
Expected body request: JSON XML
{
    "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: JSON XML
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

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

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.

Example response: JSON XML
{
    "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"
        }
    ]
}

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.

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.
  • 2754: Clause Not Parsed Clause not parsed due to invalid RuleType.
  • 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 parseable 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'.

Updating a segment

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.

PUT https://api.createsend.com/api/v3.1/segments/{segmentid}.{xml|json}
Expected body request: JSON XML
{
    "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 (both XML and JSON):

HTTP/1.1 200 OK
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:

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

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.

Example response: JSON XML
{
    "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"
        }
    ]
}

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.

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.
  • 2754: Clause Not Parsed Clause not parsed due to invalid RuleType.
  • 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 parseable 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'.

Adding a segment rulegroup

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.

POST https://api.createsend.com/api/v3.1/segments/{segmentid}/rules.{xml|json}
Expected body request: JSON XML
{
    "Rules": [
        {
            "RuleType": "Name",
            "Clause": "NOT_PROVIDED"
        },
        {
            "RuleType": "Name",
            "Clause": "EQUALS Subscriber Name"
        },
    ]
}

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.

Example response: JSON XML
{
    "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"
        }
    ]
}

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.

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.
  • 2754: Clause Not Parsed Clause not parsed due to invalid RuleType.
  • 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 parseable 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'.

Getting a segment's details

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

GET https://api.createsend.com/api/v3.1/segments/{segmentid}.{xml|json}
Expected response: JSON XML
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.

Getting active subscribers

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.

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

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.

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

{
    "Results": [
        {
            "EmailAddress": "subs+7t8787Y@example.com",
            "Name": "Person One",
            "Date": "2010-10-25 10:28:00",
            "State": "Active",
            "CustomFields": [
                {
                    "Key": "website",
                    "Value": "http://example.com"
                },
                {
                    "Key": "age",
                    "Value": "24"
                },
                {
                    "Key": "subscription date",
                    "Value": "2010-03-09"
                }
            ]
        },
        {
            "EmailAddress": "subs+7878787y8ggg@example.com",
            "Name": "Person Two",
            "Date": "2010-10-25 12:17:00",
            "State": "Active",
            "CustomFields": [
                {
                    "Key": "website",
                    "Value": "http://subdomain.example.com"
                }
            ]
        },
        {
            "EmailAddress": "subs+7890909i0ggg@example.com",
            "Name": "Person Three",
            "Date": "2010-10-25 12:52:00",
            "State": "Active",
            "CustomFields": [
                {
                    "Key": "website",
                    "Value": "http://subdomain.example.com"
                }
            ]
        },
        {
            "EmailAddress": "subs@example.com",
            "Name": "Person Four",
            "Date": "2010-10-27 13:13:00",
            "State": "Active",
            "CustomFields": []
        },
        {
            "EmailAddress": "joey@example.com",
            "Name": "Person Five",
            "Date": "2010-10-27 13:13:00",
            "State": "Active",
            "CustomFields": []
        }
    ],
    "ResultsOrderedBy": "email",
    "OrderDirection": "asc",
    "PageNumber": 1,
    "PageSize": 1000,
    "RecordsOnThisPage": 5,
    "TotalNumberOfRecords": 5,
    "NumberOfPages": 1
}
Error responses:

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

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

  • 800: Invalid page number The page number you have provided is invalid.
  • 801: Invalid page size The page size must be between 10 and 1000.
  • 802: Invalid order field The order field must be either email, name or date
  • 803: Invalid order direction The order direction must be either asc or desc
  • 5: Invalid Date The date must be provided and in the format YYYY-MM-DD

Deleting a segment

Deletes an existing segment from a subscriber list.
segmentid The ID of the segment to be deleted.

DELETE https://api.createsend.com/api/v3.1/segments/{segmentid}.{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:

  • 272: Segment Has Campaigns A segment attached to unsent campaign drafts cannot be deleted

Deleting a segment's rules

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.

DELETE https://api.createsend.com/api/v3.1/segments/{segmentid}/rules.{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.

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 satifies 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 rules collection: JSON XML
"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

Variations to RuleType and Clauses

The full range of segment types is available through the API. The following table documents all the available RuleTypes, and the respective Clause formats available for each.

RuleType Verbs Operand format Example Clause
Name EQUALS any string EQUALS Inglebert Humpledick
NOT_EQUALS any string NOT_EQUALS Spencer Fosselworth
PROVIDED ---- PROVIDED
NOT_PROVIDED ---- NOT_PROVIDED
CONTAINS any string CONTAINS Inglebert
NOT_CONTAINS any string NOT_CONTAINS Humpledick
STARTS_WITH any string STARTS_WITH Spencer
NOT_STARTS_WITH any string NOT_STARTS_WITH Spencer
ENDS_WITH any string ENDS_WITH Fosselworth
NOT_ENDS_WITH any string NOT_ENDS_WITH Fosselworth
EmailAddress EQUALS valid email EQUALS gretchen@example.com
NOT_EQUALS valid email NOT_EQUALS boris.brainstem@example.com
CONTAINS any string CONTAINS example.com
NOT_CONTAINS any string NOT_CONTAINS example.com
STARTS_WITH any string STARTS WITH gretchen
NOT_STARTS_WITH any string NOT_STARTS_WITH gretchen
ENDS_WITH any string ENDS_WITH .au
NOT_ENDS_WITH any string NOT_ENDS_WITH .au
DateSubscribed EQUALS yyyy-mm-dd EQUALS 1917-04-06
NOT_EQUALS yyyy-mm-dd NOT_EQUALS 1941-07-12
BEFORE yyyy-mm-dd BEFORE 2001-09-11
AFTER yyyy-mm-dd AFTER 1965-01-01
CampaignOpened {campaignid} ---- a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1
CampaignClickedAny {campaignid} ---- a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1
CampaignClickedSpecific {campaignid} any url from campaign a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1 http://example.com/campaign_link
CampaignNotClickedSpecific {campaignid} any url from campaign a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1 http://example.com/campaign_link
CampaignOpenedNoClick {campaignid} ---- a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1
CampaignNotOpened {campaignid} ---- a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1
[{CustomField}] See table below for details on how to construct custom field based segments

Variations to Clauses for different CustomFieldTypes

A segment rule can be created on a custom field by using the personalization tag as the RuleType. This means that a custom field called "Birthday", with a personalization tag of "[Birthday]" will use "[Birthday]" as the RuleType.

Clause formats for custom fields depend on the type of the field.

Field Type Verbs Operand format Example Clause
Text EQUALS any string EQUALS cats
NOT_EQUALS any string NOT_EQUALS killer whales
PROVIDED ---- PROVIDED
NOT_PROVIDED ---- NOT_PROVIDED
CONTAINS any string CONTAINS tea
NOT_CONTAINS any string NOT_CONTAINS coffee
STARTS_WITH any string STARTS_WITH dawn
NOT_STARTS_WITH any string NOT_STARTS_WITH dusk
ENDS_WITH any string ENDS_WITH dusk
NOT_ENDS_WITH any string NOT_ENDS_WITH dawn
Number EQUALS valid number EQUALS 42
NOT_EQUALS valid number NOT_EQUALS -1.4765
GREATER_THAN valid number GREATER_THAN -0.003
LESS_THAN valid number LESS_THAN 28354
PROVIDED ---- PROVIDED
NOT_PROVIDED ---- NOT_PROVIDED
GREATER_THAN_OR_EQUAL valid number GREATER_THAN_OR_EQUAL 10
LESS_THAN_OR_EQUAL valid number LESS_THAN_OR_EQUAL 75
BETWEEN valid number AND valid number BETWEEN -12 AND 21
MultiSelectOne or MultiSelectMany EQUALS any string EQUALS Mozambique
NOT_EQUALS any string NOT_EQUALS New Zealand
PROVIDED ---- PROVIDED
NOT_PROVIDED ---- NOT_PROVIDED
Date EQUALS yyyy-mm-dd EQUALS 1917-04-06
NOT_EQUALS yyyy-mm-dd NOT_EQUALS 1941-07-12
BEFORE yyyy-mm-dd BEFORE 2001-09-11
AFTER yyyy-mm-dd AFTER 1965-01-01
PROVIDED ---- PROVIDED
NOT_PROVIDED ---- NOT_PROVIDED
ON_OR_BEFORE yyyy-mm-dd ON_OR_BEFORE 1980-01-25
ON_OR_AFTER yyyy-mm-dd ON_OR_AFTER 1978-07-05
BETWEEN yyyy-mm-dd AND yyyy-mm-dd BETWEEN 1978-07-05 AND 1980-09-03

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

Create an account