Email Segmentation Filters

JSON filter rules for email marketing audience segments

Email marketing segments use a JSON object called filter_rules.

You can create segments in the dashboard under Marketing -> Email -> Audience -> Segments or through POST /dev/v1/email-marketing/segments.

All top-level rules are combined with AND. Empty JSON ({}) means all eligible subscribed contacts.

For keys that accept an array, entries inside that array are combined as OR. For example, "country": ["DE", "AT"] means Germany or Austria.

Product purchase

Use product filters when you want customers who bought a specific product. Product filters match paid invoices with status COMPLETED, PARTIAL_REFUND, or REFUNDED. Developer invoices are excluded.

{
  "product_id": "PRODUCT_ID_OR_UNIQID"
}

Multiple products:

{
  "product_ids": ["PRODUCT_ID_1", "PRODUCT_UNIQID_2"]
}

Nested form:

{
  "product": {
    "uniqids": ["product_abc", "product_def"]
  }
}

Supported product keys:

Key	Value
product_id	string
product_ids	string array
productId	string
productIds	string array
product.id	string
product.ids	string array
product.product_id	string
product.product_ids	string array
product.productId	string
product.productIds	string array
product.uniqid	string
product.uniqids	string array

Spending

Spending filters use the customer profile total_spent field.

Customers who spent at least 100:

{
  "min_total_spent": 100
}

Customers who spent at most 500:

{
  "max_total_spent": 500
}

Range:

{
  "min_total_spent": 100,
  "max_total_spent": 500
}

CamelCase is also supported:

{
  "minTotalSpent": 100,
  "maxTotalSpent": 500
}

Order count

Order count filters use the customer profile order_count field.

{
  "min_order_count": 2
}

{
  "max_order_count": 10
}

CamelCase is also supported:

{
  "minOrderCount": 2,
  "maxOrderCount": 10
}

Country

Country filters use ISO 3166-1 alpha-2 country codes from the customer profile.

{
  "country": "DE"
}

Multiple countries:

{
  "country": ["DE", "AT", "CH"]
}

country_code is also supported:

{
  "country_code": "US"
}

country_code can also be an array.

Tags

Match one tag:

{
  "tags": {
    "contains": "vip"
  }
}

Match any tag:

{
  "tags": {
    "any": ["vip", "wholesale"]
  }
}

Require all tags:

{
  "tags": {
    "all": ["vip", "repeat-buyer"]
  }
}

Consent basis

Segments can narrow contacts to a specific marketing consent basis. Campaign sends only include eligible subscribed contacts.

{
  "consent_basis": "SOFT_OPT_IN"
}

{
  "consent_basis": "CONSENT"
}

consent is also supported:

{
  "consent": "CONSENT"
}

Both consent_basis and consent can also be arrays:

{
  "consent_basis": ["CONSENT", "SOFT_OPT_IN"]
}

Source

Use source when you need contacts created through a specific path.

{
  "source": "backfill:paid_invoice"
}

Multiple sources:

{
  "source": ["customer_portal", "backfill:paid_invoice"]
}

Examples of common sources include customer_portal, dev-api, manual, backfill:paid_invoice, and automation sources like automation:post_purchase.

Last activity

Last activity filters use the email contact updated_at timestamp.

{
  "last_activity": {
    "within_days": 30
  }
}

CamelCase is also supported:

{
  "lastActivity": {
    "withinDays": 30
  }
}

Combined examples

Customers from Germany who bought a product and spent at least 100:

{
  "country": "DE",
  "product_id": "PRODUCT_ID_OR_UNIQID",
  "min_total_spent": 100
}

VIP customers in DACH countries who ordered at least twice:

{
  "country": ["DE", "AT", "CH"],
  "tags": {
    "contains": "vip"
  },
  "min_order_count": 2
}

Recent paid-invoice contacts for one product:

{
  "source": "backfill:paid_invoice",
  "product_id": "PRODUCT_ID_OR_UNIQID",
  "last_activity": {
    "within_days": 30
  }
}

Data source notes

• Product filters use paid invoice line items.
• Spending, order count, and country filters use customer profile fields.
• Tags, consent basis, source, and last activity use email audience contact fields.
• Contacts must still be subscribed, send-eligible, and linked to a known customer or paid buyer.