Segments

Segments may be created or updated with the API. The JSON structure of a segment is:

{
  "name": "Opened Campaign",
  "operator": "all",
  "conditions": [
    {
      "type": "campaign_activity",
      "operator": "clicked"
    },
    {
      "type": "field",
      "id": "66e60ece-d4e4-4286-8ea6-990cb500aa8e",
      "operator": "is greater than",
      "integer_value": 1
    }
  ]
}

The "operator" property can have the values all or any. If all, a contact must match all conditions to be part of the segment. If any, a contact must match at least one of the conditions to be part of the segment.

Conditions

Conditions must be JSON objects. Please reference the list below for examples of valid condition objects.

Field

A field condition tests against the values of your contact's fields.

Text

{
  "type": "field",
  "id": "10f6a31c-d788-11f0-8c4e-acde48001122",
  "operator": "is",
  "text_value": "member"
}

type - must be equal to field.
id - ID of the field.
operator - One of the following:
- is
- is not
- starts with
- contains
- does not contain
text_value - A string to test against the field value using the given operator.

Email

{
  "type": "field",
  "id": "10f6a31c-d788-11f0-8c4e-acde48001122",
  "operator": "domain is",
  "email_value": "gmail.com"
}

type - must be equal to field.
id - ID of the field.
operator - One of the following:
- is
- is not
- starts with
- contains
- does not contain
- domain is
- domain is not
email_value - A string to test against the field value using the given operator.

Integer

{
  "type": "field",
  "id": "10f6a31c-d788-11f0-8c4e-acde48001122",
  "operator": "is greater than",
  "integer_value": 1
}

type - must be equal to field.
id - ID of the field.
operator - One of the following:
- is
- is not
- is greater than
- is less than
text_value - An integer to test against the field value using the given operator.

Date

{
  "type": "field",
  "id": "10f6a31c-d788-11f0-8c4e-acde48001122",
  "operator": "is",
  "date_value": "2024-12-10"
}

type - must be equal to field.
id - ID of the field.
operator - One of the following:
- is
- is not
- is greater than
- is less than
date_value - A date in the format YYYY-MM-DD to test against the field value using the given operator.

Segment Reference

A segment reference condition tests another segment matches or does not match.

{
  "type": "reference",
  "id": "10f6a31c-d788-11f0-8c4e-acde48001122",
  "operator": "does not match"
}

type - must be equal to reference.
id - ID of the segment.
operator - One of the following:
- matches
- does not match

Date Added

A date added condition tests against the creation date of your contacts.

Date Value

{
  "type": "date_added",
  "operator": "is",
  "date_value": "2024-10-11"
}

type - must be equal to date_added.
operator - One of the following:
- is
- is not
- is less than
- is greater than
date_value - A date in the format YYYY-MM-DD to test against the creation date using the given operator.

Days Value

{
  "type": "date_added",
  "operator": "not in the last",
  "days": 10
}

type - must be equal to date_added.
operator - One of the following:
- in the last
- not in the last
days - A number of days to test against the creation date using the given operator.

Campaign Activity

A campaign activity condition tests your contacts interaction with campaigns.

Any Campaign

{
  "type": "campaign_activity",
  "operator": "complained on"
}

type - must be equal to campaign_activity.
operator - One of the following:
- opened
- did not open
- clicked
- did not click
- was sent
- was not sent
- unsubscribed from
- did not unsubscribe from
- converted on
- did not convert on
- was delivered
- was not delivered
- complained on
- did not complain on
- hard bounced on
- did not hard bounce on
- soft bounced on
- did not soft bounce on
Specific Campaign
```
{
  "type": "campaign_activity",
  "operator": "hard bounced on",
  "id": "10f6a31c-d788-11f0-8c4e-acde48001122
}
```

type - must be equal to campaign_activity.
operator - One of the following:
- opened
- did not open
- clicked
- did not click
- was sent
- was not sent
- unsubscribed from
- did not unsubscribe from
- converted on
- did not convert on
- was delivered
- was not delivered
- complained on
- did not complain on
- hard bounced on
- did not hard bounce on
- soft bounced on
- did not soft bounce on
id - A specific campaign the operator must match on.

In the Last N Days

{
  "type": "campaign_activity",
  "operator": "did not open",
  "id": "10f6a31c-d788-11f0-8c4e-acde48001122",
  "days": 10
}

type - must be equal to campaign_activity.
operator - One of the following:
- opened
- did not open
- clicked
- did not click
- was sent
- was not sent
- unsubscribed from
- did not unsubscribe from
- converted on
- did not convert on
id - A specific campaign the operator must match on. Omit to allow any campaign to match.
days - The campaign must match the operator within this number of days.

Subscription

A subscription condition tests whether your contacts are subscribed or unsubscribed to your message types.

All or Some Message Types

{
  "type": "subscription",
  "operator": "subscribed to",
  "quantifier": "some"
}

type - must be equal to subscription.
operator - One of the following:
- subscribed to
- not subscribed to
quantifier - Either some or all. "some" means at least one message type. "all" means all message types.

Specific Message Type

{
  "type": "subscription",
  "operator": "not subscribed to",
  "id": "10f6a31c-d788-11f0-8c4e-acde48001122"
}

type - must be equal to subscription.
operator - One of the following:
- subscribed to
- not subscribed to
id - The id of a specific message type the operator must match on.

Location

Contact Near a Point

{
  "type": "location",
  "operator": "within",
  "distance": 1.5,
  "point": [1.25, 1.25]
}

type - must be equal to location.
operator - One of the following:
- is within
distance - A distance in miles the contacts last location must be within
point - The latitude and longitude of a point on Earth.

Contact Is in Country or State

{
  "type": "location",
  "operator": "is not in country",
  "geoname_id": 3041565
}

type - must be equal to location.
operator - One of the following:
- is in country
- is not in country
- is in us state
- is not in us state
geoname_id - An integer representing a GeoName. See www.geonames.com.

Contact Is in Postal Code

{
  "type": "location",
  "operator": "is postal code",
  "postal_code": "79920"
}

type - must be equal to location.
operator - One of the following:
- is postal code
- is not postal code
postal_code - A string containing a postal code.