Filters

Filters let you target specific contacts when sending a newsletter. Each filter narrows the recipient list by tags, lists, topics, attributes, signup date, newsletter engagement, or location. Multiple filters can be combined with "and" or "or" connectors.

Filter Object

Fields

connectorstring

How this filter combines with the previous one. Either "and" or "or". Defaults to "and". Ignored on the first filter.

categorystring

required

The type of filter. One of "tags", "lists", "topics", "attributes", "date", "engagement", or "location".

modestring

Required for tags/lists/topics/attributes ("all", "any", "none") and location ("any", "none"). Omitted for date/engagement.

operatorstring

Required for date and engagement filters. See the Categories section for valid operators.

fieldstring

Required for location filters. Either "country" or "timezone".

valuesarray | object

required

The values to match against. Format depends on category (see below).

Combined Example

{
  "filters": [
    {
      "connector": "and",
      "category": "tags",
      "mode": "any",
      "values": [
        "vip",
        "premium"
      ]
    },
    {
      "connector": "and",
      "category": "lists",
      "mode": "all",
      "values": [
        1,
        5
      ]
    },
    {
      "connector": "or",
      "category": "attributes",
      "mode": "any",
      "values": [
        {
          "key": "plan",
          "value": "pro"
        },
        {
          "key": "status",
          "value": "active"
        }
      ]
    }
  ]
}

Categories

The values format depends on the filter category. All referenced tags, lists, and attributes must exist and belong to your account.

Lists

Array of list ID integers. Matches contacts that belong to the specified lists.

Lists Filter

{
  "connector": "and",
  "category": "lists",
  "mode": "all",
  "values": [
    1,
    5
  ]
}

Topics

Array of topic ID integers. Matches contacts that are actively subscribed to the specified topics.

Topics Filter

{
  "connector": "and",
  "category": "topics",
  "mode": "any",
  "values": [
    12,
    34
  ]
}

Attributes

Array of objects with key, operator, and value. Operators: equals, not_equals, contains, not_contains, gt, lt, is_set, is_not_set. value is ignored for is_set/is_not_set and must be numeric for gt/lt.

Attributes Filter

{
  "connector": "or",
  "category": "attributes",
  "mode": "any",
  "values": [
    {
      "key": "plan",
      "operator": "equals",
      "value": "pro"
    },
    {
      "key": "age",
      "operator": "gt",
      "value": "21"
    }
  ]
}

Date

Filters on the contact's signup date. Set operator to before/after with values: { date }, in_last/more_than with values: { days }, or between with values: { from, to }.

Date Filter

{
  "connector": "and",
  "category": "date",
  "operator": "more_than",
  "values": {
    "days": 30
  }
}

Engagement

Filters on newsletter activity. operator is one of opened, clicked, received, not_opened, not_clicked, not_received. received means the newsletter was delivered to the contact (a bounced send does not count). newsletter_id is null for any newsletter; set within to last_n_days with a days count.

Engagement Filter

{
  "connector": "and",
  "category": "engagement",
  "operator": "not_opened",
  "values": {
    "newsletter_id": null,
    "within": "last_n_days",
    "days": 90
  }
}

Location

Filters on contact country or timezone. Set field to country or timezone, mode to any or none, and values to an array of strings.

Location Filter

{
  "connector": "or",
  "category": "location",
  "field": "country",
  "mode": "any",
  "values": [
    "US",
    "GB"
  ]
}

Modes

The mode field controls how values are matched against each contact.

all

Contact must match every value in the array. For tags, the contact must have all listed tags. For lists, the contact must be in all listed lists.

any

Contact must match at least one value. For tags, the contact needs at least one of the listed tags. This is the most common mode.

none

Contact must not match any value. For tags, the contact must have none of the listed tags. Useful for excluding segments.