Segment Definition

Segment Definition

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

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

  • Must be between 0 and 100.
upper

integer

/

required

The greater number of the range of percentages to segment on within your mailing list.

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"
}

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

If no link is specified then subscribers who clicked any link within the campaign 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

/

required


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

id

integer

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

string

The campaign’s name
link

hash

/

default: null


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

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

Find subscribers based on whether they opened a campaign.

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 campaign to null means select subscribers who opened 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_opened_campaign",
  "operator": "has_not_opened",
  "campaign": {
    "id": 491
  }
}

Subscriber Clicked Campaign

Find subscribers based on whether they clicked a campaign.

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 campaign to null means select subscribers who clicked 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_clicked_campaign",
  "operator": "has_not_clicked",
  "campaign": {
    "id": 491
  }
}

Subscriber Opened / Clicked / Sent

Find subscribers based on open, click or send history.

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.

Example #1:

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

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"
}
 "Segment API"
"Subscriber Counts API"