Segment Definition

Table of Contents
Any/All
In Mailing List
Not In Suppression List
Subscriber Date Bounced / Confirmed / Subscribed / Unsubscribed / Spam Complained
In Segment
Portion
Subscriber Clicked Link
Subscriber Confirmed
Subscriber Domain
Subscriber Email
Subscriber Format
Subscriber in Campaign
Subscriber near US Zip Code
Subscriber Opened Campaign/Autoresponder
Subscriber Clicked Campaign/Autoresponder
Subscriber Most Recently Opened / Clicked / Sent
Subscriber Status
Custom Fields

Segments may be specified in the Campaigns API and the Segments API using the syntax as defined below.

The definition is an array of clauses, all of which must be true for each subscriber record to be included.

Specifying an empty array [] is equivalent to selecting “All Active Subscribers”.

Any/All

Segments support nested logic switches with any and all types.

type string / required	`any` or `all`
clauses array of hashes / required	An array of criteria definitions.

Example:

{
  "type": "any",
  "clauses": [
    { "type": "in_mailing_list", "operator": "is_in", "mailing_list_id": 12 },
    {
      "type": "all",
      "clauses": [
        { "type": "in_mailing_list", "operator": "is not in", "mailing_list_id": 13 },
        { "type": "in_mailing_list", "operator": "is not in", "mailing_list_id": 15 },
      ]
    }
  ]
}

The above example will select all subscribers who are either in mailing list id #12 or are not in mailing list id #13 or #15.

In Mailing List

The segment may include a rule restricting the included subscribers to those whose email addresses exist on another mailing list.

type
string
/
required

in_mailing_list

operator
string
/
required

is_in	Find subscribers that are in `mailing_list`
is_not_in	Find subscribers that are not in `mailing_list`
is_active_in	Find subscribers that are active in `mailing_list`
is_not_active_in	Find subscribers that are not active in the `mailing_list`

mailing_list
hash
/
required

If both an id and name are specified, the id takes precedence.

id integer	The `id` of the mailing list
name string	The `name` of the mailing list

mailing_list_id
integer
/
deprecated

The id of the mailing list

Example:

{
  "type": "in_mailing_list",
  "operator": "is_in",
  "mailing_list": { "id": 12 }
}

This campaign would be sent to “All Active Subscribers whose email addresses exist on mailing list #12”.

Not In Suppression List

The segment may include a rule restricting the included subscribers to those whose email addresses is not matched by a specific suppression list.

type
string
/
required

not_in_suppression_list

suppression_list
hash
/
required

If both an id and name are specified, the id takes precedence.

id integer	The `id` of the suppression list
name string	The `name` of the suppression list

Example:

{
  "type": "not_in_suppression_list",
  "suppression_list": { "id": 12 }
}

This campaign would be sent to “All Active Subscribers whose email addresses are not suppressed by suppression list #12”.

Subscriber Date Bounced / Confirmed / Subscribed / Unsubscribed / Spam Complained

These rules all have similar structures and functions, the only difference being the segment’s type field.

type
string
/
required

subscriber_date_bounced, subscriber_date_confirmed, subscriber_date_subscribed, subscriber_date_unsubscribed, subscriber_date_spam_complained, subscriber_date_deactivated

operator
string
/
required

not_in_the_last_days	Find subscribers who have not performed the segment type’s action within the last `number_of_days` days
in_the_last_days	Find subscribers who have performed the segment type’s action within the last `number_of_days` days
before	Find subscribers who performed the segment type’s action before the given `date`
after	Find subscribers who performed the segment type’s action after the given `date`
between	Find subscribers who performed the segment type’s action between the dates given within `date_range`
on	Find subscribers who performed the segment type’s action on the given `date`
on_or_before	Find subscribers who performed the segment type’s action on or before the given `date`
on_or_after	Find subscribers who performed the segment type’s action on or after the given `date`

number_of_days
integer

The integer number of days to search for

Required for operators: not_in_the_last_days and in_the_last_days

date
string

A string which can be parsed to a date field. See Dates and Times.

Required for operators: before, after, on, on_or_before, and on_or_after

date_range
hash

Required for operator: between

start string	A string which can be parsed to a date field for the start of the range. See Dates and Times.
end string	A string which can be parsed to a date field for the end of the range. See Dates and Times.

Example #1:

{
  "type": "subscriber_date_bounced",
  "operator": "not_in_the_last_days",
  "number_of_days": 5
}

Example #2:

{
  "type": "subscriber_date_subscribed",
  "operator": "on_or_before",
  "date": "2015-09-01"
}

Example #3:

{
  "type": "subscriber_date_spam_complained",
  "operator": "between",
  "date_range": { "start": "2015-09-01", "end": "2015-09-03" }
}

In Segment

Find subscribers based on whether they match an existing segment.

type
string

in_segmentation_criteria

operator
string

is_in	Find subscribers who match the `segmentation_criteria`
is_not_in	Find subscribers who do not match the `segmentation_criteria`

segmentation_criteria
hash

If both an id and name are specified, the id takes precedence.

id integer	The `id` of the segment.
name integer	The `name` of the segment.

Example:

{
  "type": "in_segmentation_criteria",
  "operator": "is_in",
  "segmentation_criteria": {
    "id": 456,
    "name": "Active Subscribers"
  }
}

Portion

Send to only a portion of your list based on percentages. For example, send one email to 0%-10% of your list, send a second email to 10%-20% of your list (keeping the same randomization key), then send the more successful of the two emails to 20%-100% of your list as a way to do A/B split testing on a campaign. In this example, no subscriber will be sent two emails because there are no overlapping percentage/randomization key combinations.

Portion clauses accept the following fields:

type string	`portion`
lower integer / required	The lower number of the range of percentages to segment on within your mailing list. May contain up to 2 decimals of precision. Must be between `0` and `100`.
upper integer / required	The greater number of the range of percentages to segment on within your mailing list. May contain up to 2 decimals of precision. When this number is less than 100, it will be used as an exclusive (not included) limit. When this number equals 100, it is an inclusive limit. This causes `0-50` and `50-100` to be non-overlapping. Must be between `0` and `100`.
key string	The randomization key will act as a salt for sorting your mailing list. When creating multiple `portion` segments, you will want to use the same `key` to keep the same ordering. If no key is specified, one will be generated for you. Must be no more than 50 characters in length.

Example:

{
  "type": "portion",
  "lower": 0,
  "upper": 47,
  "key": "my_randomized_key"
}

Subscriber Clicked Link

Find subscribers who have clicked a specific link within a campaign or autoresponder.

If no link is specified then subscribers who clicked any link within the campaign/autoresponder are selected.

type
string
/
required

subscriber_clicked_link

operator
string
/
required

has_clicked_on	Find subscribers who have clicked the specified link within a campaign.
has_not_clicked_on	Find subscribers who have not clicked the specified link within a campaign.

campaign
hash
/
optional

If both an id and name are specified, the id takes precedence.

Either campaign or autoresponder must be specified (but not both).

id integer	The campaign’s id. If both `name` and `id` are given, `id` will be used.
name string	The campaign’s name

autoresponder
hash
/
optional

If both an id and name are specified, the id takes precedence.

Either campaign or autoresponder must be specified (but not both).

id integer	The autoresponder’s id. If both `name` and `id` are given, `id` will be used.
name string	The autoresponder’s name

link
hash
/
default: null

Leave link blank or null to use any link within the campaign/autoresponder.

If both an id and url are specified, the id takes precedence.

id integer	The link’s id. If both `url` and `id` are given, `id` will be used.
url string	The link’s url.

Example:

{
  "type": "subscriber_clicked_link",
  "operator": "has_clicked_on",
  "campaign": {
    "id": 19
  },
  "link": {
    "id": 19
  }
}

Subscriber Confirmed

Find subscribers who have or haven’t clicked confirmation links.

This rule is only valid if the system has the confirmed field enabled and the mailing list has it turned on.

type string	`subscriber_confirmed`
confirmed boolean	Select users that have confirmed or not confirmed.

Example:

{
  "type": "subscriber_confirmed",
  "confirmed": true
}

Subscriber Domain

Find subscribers based on their email address’ domain.

type
string

subscriber_domain

operator
string

is_one_of	Find subscribers that have an email address at one of the `domains`.
is_not_one_of	Find subscribers that have an email address not at one of the `domains`.
ends_with_any_of	Find subscribers that have an email address ending with one of the `domains`. (`"yourcompany.example.com"` will match `"example.com"`)
does_not_end_with_any_of	Find subscribers that have an email address not ending with any of the `domains`.

domains
array of strings

The list of domains to compare against.

Example:

{
  "type": "subscriber_domain",
  "operator": "is_one_of",
  "domains": [ "gmail.com", "yahoo.com" ]
}

Subscriber Email

Find subscribers based on their email addresses.

type
string

subscriber_email

operator
string

All of the following email address comparisons are case-insensitive:

contains	Find subscribers with an email address that contains the given `value`
does_not_contain	Find subscribers with an email address that does not contain the given `value`
ends_with	Find subscribers with an email address that ends with the given `value`
does_not_end_with	Find subscribers with an email address that does not end with the given `value`
is	Find subscribers with an email address that is the given `value`
is_not	Find subscribers with an email address that is not the given `value`

value
string

The string value to use when comparing email addresses.

Example:

{
  "type": "subscriber_email",
  "operator": "contains",
  "value": "postmaster"
}

Subscriber Format

Find subscribers based on their preferred email format.

This rule is only valid if the mailing list has the format field enabled.

type
string

subscriber_format

operator
string

is	Find subscribers who prefer the `format` specified
is_not	Find subscribers who do not prefer the `format` specified

format
string

The format to search against. Can be html or plaintext

Example:

{
  "type": "subscriber_format",
  "operator": "is",
  "format": "html"
}

Subscriber in Campaign

Find subscribers based on whether they were sent a campaign.

type
string

subscriber_in_campaign

operator
string

was_included	Return all subscribers who are included in the `campaign`.
was_not_included	Return all subscribers who are not included in the `campaign`.

campaign
hash

Setting campaign to null means select subscribers who were sent any campaign.

If both an id and name are specified, the id takes precedence.

id integer	The `id` of the campaign
name string	The `name` of the campaign

Example:

{
  "type": "subscriber_in_campaign",
  "operator": "was_not_included",
  "campaign": {
    "id": 4912
  }
}

Subscriber near US Zip Code

Find subscribers who are more or less than a certain distance from a given zip_code.

You must have a text or number custom field already set up which will be interpreted as the subscriber’s zip_code.

type
string

subscriber_near_us_zip_code

operator
string

is_within	Find subscribers who are within `distance_in_miles` of the given `zip_code`.
is_not_within	Find subscribers who are not within `distance_in_miles` of the given `zip_code`.

distance_in_miles
integer

The distance in miles to include or exclude subscribers around the given zip_code.

zip_code
string

The zip code to base your search off of. This value can be formatted as NNNNN or NNNNN-NNNN.

zip_code_custom_field
hash

If both id and name are present, the value in name will be ignored.

id integer	The `id` of the custom field tracking subscriber zip codes.
name string	The `name` of the custom field tracking subscriber zip codes.

include_blank_values
boolean

Include subscribers with an empty value in their zip_code_custom_field.

This field must be specified when operator = "is_not_within".
This field may not be specified when operator = "is_within".

Example:

{
  "type": "subscriber_near_us_zip_code",
  "operator": "is_not_within",
  "distance_in_miles": 50,
  "zip_code": "04401",
  "zip_code_custom_field": {
    "name": "Zip Code"
  },
  "include_blank_values": true
}

Subscriber Opened Campaign/Autoresponder

Find subscribers based on whether they opened a campaign or autoresponder.

type
string

subscriber_opened_campaign

operator
string

has_opened	Return all subscribers who have opened the `campaign`.
has_not_opened	Return all subscribers who have not opened the `campaign`.

campaign
hash

Setting both campaign and autoresponder to null means select subscribers who opened any campaign or autoresponder.

Only one of campaign and autoresponder may be specified.

If both an id and name are specified, the id takes precedence.

id integer	The `id` of the campaign
name string	The `name` of the campaign

autoresponder
hash

Setting both campaign and autoresponder to null means select subscribers who opened any campaign or autoresponder.

Only one of campaign and autoresponder may be specified.

If both an id and name are specified, the id takes precedence.

id integer	The `id` of the autoresponder
name string	The `name` of the autoresponder

privacy_status
string

Valid values include: any (default), privacy, non-privacy

Limit the open events that are searched to only match on any, privacy, or non-privacy opens.

Because Apple’s Mail Privacy Protection stops triggering privacy opens when mail is delivered to the bulk folder, it can be useful in various situations to match on a variety of open types. Non-privacy opens tell you that a subscriber actually opened the email. Privacy opens tell you that the email reached the inbox.

Example:

{
  "type": "subscriber_opened_campaign",
  "operator": "has_not_opened",
  "campaign": {
    "id": 491
  },
  "privacy_status": "non-privacy"
}

Subscriber Clicked Campaign/Autoresponder

Find subscribers based on whether they clicked a campaign or autoresponder.

type
string

subscriber_clicked_campaign

operator
string

has_clicked	Return all subscribers who have clicked the `campaign`.
has_not_clicked	Return all subscribers who have not clicked the `campaign`.

campaign
hash

Setting both campaign and autoresponder to null means select subscribers who clicked any campaign or autoresponder.

Only one of campaign and autoresponder may be specified.

If both an id and name are specified, the id takes precedence.

id integer	The `id` of the campaign
name string	The `name` of the campaign

autoresponder
hash

Setting both campaign and autoresponder to null means select subscribers who clicked any campaign or autoresponder.

Only one of campaign and autoresponder may be specified.

If both an id and name are specified, the id takes precedence.

id integer	The `id` of the autoresponder
name string	The `name` of the autoresponder

Example:

{
  "type": "subscriber_clicked_campaign",
  "operator": "has_not_clicked",
  "campaign": {
    "id": 491
  }
}

Subscriber Most Recently Opened / Clicked / Sent

Find subscribers based on their most recent open, click, or send.

type
string

subscriber_opened, subscriber_clicked, or subscriber_sent

operator
string

not_in_the_last_days	Find subscribers who have not performed the segment type’s action within the last `number_of_days` days
in_the_last_days	Find subscribers who have performed the segment type’s action within the last `number_of_days` days
before	Find subscribers who performed the segment type’s action before the given `date`
after	Find subscribers who performed the segment type’s action after the given `date`
between	Find subscribers who performed the segment type’s action between the dates given within `date_range`
on	Find subscribers who performed the segment type’s action on the given `date`
on_or_before	Find subscribers who performed the segment type’s action on or before the given `date`
on_or_after	Find subscribers who performed the segment type’s action on or after the given `date`

number_of_days
integer

The integer number of days to search for

Required for operators: not_in_the_last_days and in_the_last_days

date
string

A string which can be parsed to a date field. See Dates and Times.

Required for operators: before, after, on, on_or_before, and on_or_after

date_range
hash

Required for operator: between

start string	A string which can be parsed to a date field. See Dates and Times.
end string	A string which can be parsed to a date field. See Dates and Times.

privacy_status
string

This field is only valid when type is subscriber_opened.

Valid values include: any (default), privacy, non-privacy

Limit the open events that are searched to only match on any, privacy, or non-privacy opens.

Example #1:

{
  "type": "subscriber_opened",
  "operator": "not_in_the_last_days",
  "number_of_days": 5,
  "privacy_status": "any"
}

Example #2:

{
  "type": "subscriber_clicked",
  "operator": "on_or_before",
  "date": "2015-09-01"
}

Example #3:

{
  "type": "subscriber_sent",
  "operator": "between",
  "date_range": { "start": "2015-09-01", "end": "2015-09-03" }
}

Subscriber Status

Find subscribers which do or do not have the given status.

type
string

subscriber_status

operator
string

is	Find subscribers with the given `status` value.
is_not	Find subscribers without the given `status` value.

status
string

active, unsubscribed, scomp, bounced, or deactivated

Example:

{
  "type": "subscriber_status",
  "operator": "is_not",
  "status": "active"
}

Custom Fields

Here are two example custom field criteria:

[
  { "type": "subscriber_custom_field", "name": "Age", "operator": "is_greater_than", "value": 20 },
  { "type": "subscriber_custom_field", "name": "Membership", "operator": "contains", "value": "newsletter" }
]

The above matches subscribers that are over 20 years of Age and have the “newsletter” Membership.

Each custom field has a list of operators that define how to match subscribers using the specified custom field. See the tables below for a listing of what operators each kind of custom field supports.

Text Fields

The following operators apply to both text and text_multiline custom fields:

contains	The given `value` appears somewhere in this custom field, case insensitive. `{ "type": "subscriber_custom_field", "name": "First Name", "operator": "contains", "value": "bob" }`
does_not_contain	The given `value` does not appear anywhere in this custom field, case insensitive. `{ "type": "subscriber_custom_field", "name": "First Name", "operator": "does_not_contain", "value": "bob" }`
is	The given `value` matches the custom field exactly, case sensitive. `{ "type": "subscriber_custom_field", "name": "First Name", "operator": "is", "value": "bob" }`
is_not	The given `value` does not match the custom field exactly, case sensitive. `{ "type": "subscriber_custom_field", "name": "First Name", "operator": "is_not", "value": "bob" }`
is_not_set	The custom field has no value. This may either be because it has never been set or it was set to `""`. `{ "type": "subscriber_custom_field", "name": "First Name", "operator": "is_not_set" }`
begins_with	The custom field begins with the given `value`, case insensitive. `{ "type": "subscriber_custom_field", "name": "First Name", "operator": "begins_with", "value": "bob" }`
ends_with	The custom field ends with the given `value`, case insensitive. `{ "type": "subscriber_custom_field", "name": "First Name", "operator": "ends_with", "value": "bob" }`

Boolean Fields

The following operators apply to boolean custom fields:

true

The custom field is set to true.

{
  "type": "subscriber_custom_field",
  "name": "First Name",
  "operator": "true"
}

false

The custom field is either set to false or has no value.

{
  "type": "subscriber_custom_field",
  "name": "First Name",
  "operator": "false"
}

Date Fields

The following operators apply to date custom fields:

before	The custom field is set equal to a date before the specified `value`. `{ "type": "subscriber_custom_field", "name": "Birth Date", "operator": "before", "value": "2000-05-01" }`
after	The custom field is set equal to a date after the specified `value`. `{ "type": "subscriber_custom_field", "name": "Birth Date", "operator": "after", "value": "2000-12-01" }`
between	The custom field is between the `start` and `end` dates, inclusive. `{ "type": "subscriber_custom_field", "name": "Birth Date", "operator": "between", "start": "2000-01-01", "end": "2000-12-31" }`
is_not_set	The custom field has no date set. `{ "type": "subscriber_custom_field", "name": "Birth Date", "operator": "is_not_set" }`
in_the_last_days	The custom field is sometime in the last `value` number of days. For example, if the example clause below is evaluated on `2016-05-10`, then it will match subscribers with a custom field value of `2016-05-08` through `2016-05-10`. `{ "type": "subscriber_custom_field", "name": "First Name", "operator": "in_the_last_days", "value": 2 }`
not_in_the_last_days	The custom field is not sometime in the last `value` number of days. For example, if the example clause below is evaluated on `2016-05-10`, then it will match subscribers with a custom field value before `2016-05-08` and after `2016-05-10`. `{ "type": "subscriber_custom_field", "name": "First Name", "operator": "not_in_the_last_days", "value": "2" }`

Day of Year Fields

The following operators apply to day_of_year custom fields:

before	Find subscribers who have the custom field set to a value that’s earlier in the year than the specified `value`. The `value` may be specified as `12/31` (MM/DD) or as a whole date `2016-12-31` (YYYY-MM-DD). In either case, only the `month` and `day` values are compared when matching. `{ "type": "subscriber_custom_field", "name": "Birth Day", "operator": "before", "value": "07/04" }`
after	Find subscribers who have the custom field set to a value that’s later in the year than the specified `value`. The `value` may be specified as `12/31` (MM/DD) or as a whole date `2016-12-31` (YYYY-MM-DD). In either case, only the `month` and `day` values are compared when matching. `{ "type": "subscriber_custom_field", "name": "Birth Day", "operator": "after", "value": "2016-07-04" }`
between	Find subscribers who have the custom field set to a value that’s equal to or between the specified `start` and `end` days. The `start` and `end` may be specified as `12/31` (MM/DD) or as a whole date `2016-12-31` (YYYY-MM-DD). In either case, only the `month` and `day` values are compared when matching. `{ "type": "subscriber_custom_field", "name": "Birth Day", "operator": "between", "start": "07/01", "end": "07/31" }`
is_not_set	The custom field has no day of year set. `{ "type": "subscriber_custom_field", "name": "Birth Day", "operator": "is_not_set" }`
on	The custom field is the specified `value` day of year. The `value` may be specified as `12/31` (MM/DD) or as a whole date `2016-12-31` (YYYY-MM-DD). In either case, only the `month` and `day` values are compared when matching. `{ "type": "subscriber_custom_field", "name": "Birth Day", "operator": "on", "value": "03/02" }`

Number Fields

The following operators apply to number custom fields:

equals	The given `value` exactly matches the custom field. `{ "type": "subscriber_custom_field", "name": "Number of Pets", "operator": "equals", "value": "3" }`
does_not_equal	The given `value` does not exactly match the custom field. All subscribers with no value set will also be included in this match. `{ "type": "subscriber_custom_field", "name": "Account Type", "operator": "does_not_equal", "value": 17 }`
is_less_than	The custom field is less than the given `value`. Subscribers with no value set will not be matched. `{ "type": "subscriber_custom_field", "name": "Number of Pets", "operator": "is_less_than", "value": "1" }`
is_greater_than	The custom field is greater than the given `value`. Subscribers with no value set will not be matched. `{ "type": "subscriber_custom_field", "name": "Number of Pets", "operator": "is_greater_than", "value": "0" }`
is_between	The custom field is between the `start` and `end` values, inclusive. `{ "type": "subscriber_custom_field", "name": "Number of Pets", "operator": "is_between", "start": 1, "end": 10 }`
is_not_between	The custom field is not between the `start` and `end` values, inclusive. All subscribers with no value set will also be matched. `{ "type": "subscriber_custom_field", "name": "Number of Pets", "operator": "is_not_between", "start": 1, "end": 10 }`
is_not_set	The custom field has no value set. `{ "type": "subscriber_custom_field", "name": "Number of Children", "operator": "is_not_set" }`

Single Selection Fields

The following operators apply to select_single_dropdown and select_single_radio custom fields:

any_of

The custom field is set to one of the specified values, case insensitive.

{
  "type": "subscriber_custom_field",
  "name": "Favorite Type of Pet",
  "operator": "any_of",
  "values": [ "Cat", "Dog", "Fish" ]
}

is_not_set

The custom field has no value selected.

{
  "type": "subscriber_custom_field",
  "name": "Favorite Type of Pet",
  "operator": "is_not_set"
}

Multiple Selection Fields

The following operators apply to select_multiple_checkboxes custom fields:

any_of	The selected custom field options contain at least one of the specified values, case insensitive. `{ "type": "subscriber_custom_field", "name": "Types of Pets", "operator": "any_of", "values": [ "Cat", "Dog", "Fish" ] }`
all_of	The selected custom field options contain all of the specified values, case insensitive. `{ "type": "subscriber_custom_field", "name": "Types of Pets", "operator": "all_of", "values": [ "Cat", "Dog", "Fish" ] }`
none_of	The selected custom field options contain none of the specified values, case insensitive. Subscribers with no value selected will also be included in this match. `{ "type": "subscriber_custom_field", "name": "Types of Pets", "operator": "none_of", "values": [ "Cat", "Dog", "Fish" ] }`
is_not_set	The custom field has no value selected. `{ "type": "subscriber_custom_field", "name": "Types of Pets", "operator": "is_not_set" }`