Segments

Creating a segment

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

The Rules collection is optional. Individual Rules can also be added incrementally.
Rules 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 above creates a segment of any subscribers from 'domain.com' who subscribed at any point during the year 2009.

Request:

POST

http://api.createsend.com/api/v3/segments/{listid}.{xml|json}

Route Values:

{listid}

The ID of the list on which the segment should be created.

Expected Request Body: JSON XML

	                {
                      "Title": "My Segment",
                      "Rules": [
                        {
                          "Subject": "EmailAddress",
                          "Clauses": ["CONTAINS @domain.com"]
                        },
                        {
                          "Subject": "DateSubscribed",
                          "Clauses": [
                            "AFTER 2009-01-01",
                            "EQUALS 2009-01-01"
                          ]
                        },
                        {
                          "Subject": "DateSubscribed",
                          "Clauses": [
                            "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.

Some "400 Bad Request" responses for this request will just contain the normal result object:

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

When there is a problem parsing the Rules, the Result will contain an addition 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 collection 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

Subject

The original subject, 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.

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

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:

2700: Empty Segment Subject

The Subject of a rule cannot be empty

2701: Invalid Segment Subject

The Subject of a rule must be one of "Name", "EmailAddress", "DateSubscribed", "CampaignOpened", "CampaignClickedAny", "CampaignClickedSpecific", "CampaignOpenedNoClick", "CampaignNotOpened", or the personalisation tag of any custom field on the list.

2702: Empty Segment Clauses

Any segment rule must have at least one clause

2703: Invalid Segment Clauses

At least one of the Clauses in this Rule could not be parsed. Check the ClauseResults for details.

Possible codes which could appear as part of a ClauseResult:

2710: Empty Clause

A clause cannot be empty

2711: Clause Unparsed

Due to errors in the Subject, we were unable to parse this Clause. Fix the Subject and resubmit

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

Updating a segment

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

Updating a segment will always attempt to change the Title, which is compulsory.
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.

Request:

PUT

http://api.createsend.com/api/v3/segments/{segmentid}.{xml|json}

Route Values:

{segmentid}

The ID of the segment to be updated.

Expected Request Body: JSON XML

	                {
                      "Title": "My Segment",
                      "Rules": [
                        {
                          "Subject": "EmailAddress",
                          "Clauses": ["CONTAINS @domain.com"]
                        },
                        {
                          "Subject": "DateSubscribed",
                          "Clauses": [
                            "AFTER 2009-01-01",
                            "EQUALS 2009-01-01"
                          ]
                        },
                        {
                          "Subject": "DateSubscribed",
                          "Clauses": [
                            "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.

Some "400 Bad Request" responses for this request will just contain the normal result object:

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.

Invalid Rules Error Responses JSON XML

When there is a problem parsing the Rules, the Result will contain an addition 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 collection 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

Subject

The original subject, 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.

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

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:

2700: Empty Segment Subject

The Subject of a rule cannot be empty

2701: Invalid Segment Subject

The Subject of a rule must be one of "Name", "EmailAddress", "DateSubscribed", "CampaignOpened", "CampaignClickedAny", "CampaignClickedSpecific", "CampaignOpenedNoClick", "CampaignNotOpened", or the personalisation tag of any custom field on the list.

2702: Empty Segment Clauses

Any segment rule must have at least one clause

2703: Invalid Segment Clauses

At least one of the Clauses in this Rule could not be parsed. Check the ClauseResults for details.

Possible codes which could appear as part of a ClauseResult:

2710: Empty Clause

A clause cannot be empty

2711: Clause Unparsed

Due to errors in the Subject, we were unable to parse this Clause. Fix the Subject and resubmit

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

Adding a segment rule

Adds a new rule to an existing segment. Adding a Rule will not remove any existing rules on the segment, but simply add an additional requirement for membership.

Request:

POST

http://api.createsend.com/api/v3/segments/{segmentid}/rules.{xml|json}

Route Values:

{segmentid}

The ID of the segment to which the rule will be added.

Expected Request Body: JSON XML

	                {
                      "Subject": "Name",
                      "Clauses": [
                        "NOT_PROVIDED",
                        "EQUALS Subscriber Name"
                      ]
                    }

Invalid Rules Error Responses JSON XML

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

Some "400 Bad Request" responses will return an expanded Result object with an additional element, called ResultData, which will be a collection of ClauseResult objects. This will assist in determining the nature of the problem and reconstructing a better rule.

Every Clause in the original Clauses collection will have a matching ClauseResult in this collection, containing the following elements:

Code

The result code for this Rule

Message

An explanatory message for this result code

Clause

The original clauses, for debugging and matching purposes

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

                  {
                    "ResultData": [
                      {
                        "Clause": "EQUALS Gertrude Gainforth",
                        "Code": 0,
                        "Message": "Success"
                      },
                      {
                        "Clause": "CONTAINS President",
                        "Code": 2712,
                        "Message": "Verb is illegal for Name-based rules"
                      }
                    ],
                    "Code": 2703,
                    "Message": "The supplied clauses have some problems"
                  }

Possible codes which could appear in the base Result:

2700: Empty Segment Subject

The Subject of a rule cannot be empty

2701: Invalid Segment Subject

The Subject of a rule must be one of "Name", "EmailAddress", "DateSubscribed", "CampaignOpened", "CampaignClickedAny", "CampaignClickedSpecific", "CampaignOpenedNoClick", "CampaignNotOpened", or the personalisation tag of any custom field on the list.

2702: Empty Segment Clauses

Any segment rule must have at least one clause

2703: Invalid Segment Clauses

At least one of the Clauses in this Rule could not be parsed. Check the ClauseResults for details.

Possible codes which could appear as part of a ClauseResult:

2710: Empty Clause

A clause cannot be empty

2711: Clause Unparsed

Due to errors in the Subject, we were unable to parse this Clause. Fix the Subject and resubmit

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

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.

Request:

GET

http://api.createsend.com/api/v3/segments/{segmentid}.{xml|json}

Route Values:

{segmentid}

The ID of the segment to be retrieved.

Response:

Contains the segment with full details. See here for more information on the Rules object

Expected Response: JSON XML

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

                  {
                    "ActiveSubscribers": 0,
                    "Rules": [
                      {
                        "Subject": "Subject1",
                        "Clauses": [
                          "Clause1_1",
                          "Clause1_2"
                        ]
                      },
                      {
                        "Subject": "Subject2",
                        "Clauses": [
                          "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 segment 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.

Request:

GET

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

Route Values:

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

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

Request:

DELETE

http://api.createsend.com/api/v3/segments/{segmentid}.{xml|json}

Route Values:

{segmentid}

The ID of the segment to be deleted.

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.

Some "400 Bad Request" responses for this request will just contain the normal result object:

272: Segment Has Campaigns

A segment attached to unsent campaign drafts cannot be deleted

Deleting a segment's rules

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

Request:

DELETE

http://api.createsend.com/api/v3/segments/{segmentid}/rules.{xml|json}

Route Values:

{segmentid}

The ID of the segment whose rules are to be deleted.

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 Rules. The rules are joined together by means of a logical AND, so that any subscriber who satifies all of the rules is a member of the segment.

Rules themselves consist of a Subject, and a collection of Clauses which will operate on that Subject. Clauses are simply strings which consist of an operating Verb and in most cases an Object (or operand). The Clauses within a Rule are joined together by a logical OR, so that a subscriber only has to meet one of those conditions to satisfy that rule.

The Rules collection

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

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

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

Example Rules Collection: JSON XML

                    "Rules": [
                      {
                        "Subject": "EmailAddress",
                        "Clauses": ["CONTAINS @domain.com"]
                      },
                      {
                        "Subject": "DateSubscribed",
                        "Clauses": [
                          "AFTER 2009-01-01",
                          "EQUALS 2009-01-01"
                        ]
                      },
                      {
                        "Subject": "DateSubscribed",
                        "Clauses": [
                          "BEFORE 2010-01-01"
                        ]
                      },
                      {
                        "Subject": "[Frequency]",
                        "Clauses": [
                          "NOT_EQUALS Emergency Only",
                        ]
                      },
                      {
                        "Subject": "CampaignOpened",
                        "Clauses": [
                          "1234123412341234",
                          "abcdabcdabcdabcd"
                        ]
                      }
                    ]

Interpreting the rules:

In the collection above we have five different rules:

A subject of EmailAddress means we are filtering subscribers on the basis of their email address. With only one clause in the collection the segment will pick up any subscribers whose email contains "@domain.com"
DateSubscribed means filtering on the of the list member's subscription date. Two clauses are in its collection, meaning a subscriber needs to have a date either AFTER or ON January 1st 2009.
The third clause also filters on DateSubscribed, requiring that the subscription date be before January 1st 2010.
Then we filter on the [Frequency] custom field, picking only those subscribers not registered to "Emergency Only" communications.
Finally, using CampaignOpened means we filter on whether or not they opened particular campaigns. 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:

Their email address contains "@domain.com"
They subscribed:
- On 1st January 2009
- AFTER 1st January 2009
They subscribed before 1st January 2010
Their [Frequency] custom field is not equal to "Emergency Only"
They opened one of the following campaigns:
- 1234123412341234
- abcdabcdabcdabcd

Variations to Subject and Clauses

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

Subject	Verbs	Operand format	Example Clause
Name	EQUALS NOT_EQUALS PROVIDED NOT_PROVIDED	any string any string ---- ----	EQUALS Inglebert Humpledick NOT_EQUALS Spencer Fosselworth PROVIDED NOT_PROVIDED
EmailAddress	EQUALS NOT_EQUALS CONTAINS NOT_CONTAINS	valid email valid email any string any string	EQUALS gretchen@example.com NOT_EQUALS boris.brainstem@example.com CONTAINS example.com NOT_CONTAINS example.com
DateSubscribed	EQUALS NOT_EQUALS BEFORE AFTER	yyyy-mm-dd yyyy-mm-dd yyyy-mm-dd yyyy-mm-dd	EQUALS 1917-04-06 NOT_EQUALS 1941-07-12 BEFORE 2001-09-11 AFTER 1965-01-01
CampaignOpened	{campaignid}	----	a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1
CampaignClickedAny	{campaignid}	----	a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1
CampaignClickedSpecific	{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 Subject. This means that a custom field called "Birthday", with a personalization tag of "[Birthday]" will use "[Birthday]" as the Subject.

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

Field Type	Verbs	Operand format	Example Clause
Text	EQUALS NOT_EQUALS PROVIDED NOT_PROVIDED	any string any string ---- ----	EQUALS cats NOT_EQUALS killer whales PROVIDED NOT_PROVIDED
Number	EQUALS NOT_EQUALS GREATER_THAN LESS_THAN PROVIDED NOT_PROVIDED	valid number valid number valid number valid number ---- ----	EQUALS 42 NOT_EQUALS -1.4765 GREATER_THAN -0.003 LESS_THAN 28354 PROVIDED NOT_PROVIDED
MultiSelectOne or MultiSelectMany	EQUALS NOT_EQUALS PROVIDED NOT_PROVIDED	any string any string ---- ----	EQUALS Mozambique NOT_EQUALS New Zealand PROVIDED NOT_PROVIDED
Date	EQUALS NOT_EQUALS BEFORE AFTER PROVIDED NOT_PROVIDED	yyyy-mm-dd yyyy-mm-dd yyyy-mm-dd yyyy-mm-dd ---- ----	EQUALS 1917-04-06 NOT_EQUALS 1941-07-12 BEFORE 2001-09-11 AFTER 1965-01-01 PROVIDED NOT_PROVIDED

API Documentation

Creating a segment

Request:

POST

Route Values:

{listid}

Expected Request Body: JSON XML

Response:

Expected Response: JSON XML

Basic Error Responses:

273: Segment Title Empty

275: Duplicate Segment Title

277: Invalid Segment Rules

Invalid Rules Error Responses JSON XML

Code

Message

Subject

ClauseResults

2700: Empty Segment Subject

2701: Invalid Segment Subject

2702: Empty Segment Clauses

2703: Invalid Segment Clauses

2710: Empty Clause

2711: Clause Unparsed

2712: Invalid Verb For Name Rule

2713: Invalid Verb For Email Rule

2714: Invalid Verb For DateSubscribed Rule

2715: Invalid Verb For Text Field Rule

2716: Invalid Verb For Number Field Rule

2717: Invalid Verb For Multi-Option Field Rule

2718: Invalid Verb For Date Field Rule

2719: Required Clause Object Missing

2720: Invalid Date Format

2721: Invalid Number Format

2722: Option Doesnt Exist For Field

2723: Invalid year for Date Subscribed

2750: Valid CampaignID Required

2751: Campaign Not Sent To List

2753: Link Not In Campaign

Updating a segment

Request:

PUT

Route Values:

{segmentid}

Expected Request Body: JSON XML

Expected Response (both XML and JSON):

Basic Error Responses:

272: Segment Has Campaigns

273: Segment Title Empty

275: Duplicate Segment Title

277: Invalid Segment Rules

Invalid Rules Error Responses JSON XML

Code

Message

Subject

ClauseResults

2700: Empty Segment Subject

2701: Invalid Segment Subject

2702: Empty Segment Clauses

2703: Invalid Segment Clauses

2710: Empty Clause

2711: Clause Unparsed

2712: Invalid Verb For Name Rule

2713: Invalid Verb For Email Rule

2714: Invalid Verb For DateSubscribed Rule

2715: Invalid Verb For Text Field Rule

2716: Invalid Verb For Number Field Rule

2717: Invalid Verb For Multi-Option Field Rule

2718: Invalid Verb For Date Field Rule

2719: Required Clause Object Missing

2720: Invalid Date Format

2721: Invalid Number Format

2722: Option Doesnt Exist For Field

2723: Invalid year for Date Subscribed

2750: Valid CampaignID Required

2751: Campaign Not Sent To List

2753: Link Not In Campaign

Adding a segment rule

Request: