Segmentation

Create dynamic contact segments with filter groups, nested logic, and async computation.

Segments let you group contacts based on filters — contact fields, account data, metadata, firmographic attributes, and behavioral events. Segments are computed asynchronously and can be used for targeting in journeys and experiments.

Create a segment

POST https://api.molted.email/v1/segments

curl

curl -X POST https://api.molted.email/v1/segments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "tenant_abc123",
    "name": "Enterprise customers in US",
    "filterGroup": {
      "logic": "and",
      "filters": [
        { "type": "contact_field", "field": "lifecycleStage", "operator": "eq", "value": "customer" },
        { "type": "metadata", "field": "region", "operator": "eq", "value": "us-west" },
        { "type": "firmographic", "field": "companySize", "operator": "gte", "value": 500 }
      ]
    }
  }'

List segments

GET https://api.molted.email/v1/segments

curl

curl "https://api.molted.email/v1/segments?tenantId=tenant_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update a segment

PATCH https://api.molted.email/v1/segments/:id

curl

curl -X PATCH https://api.molted.email/v1/segments/SEGMENT_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enterprise US (updated)",
    "filterGroup": {
      "logic": "and",
      "filters": [
        { "type": "contact_field", "field": "lifecycleStage", "operator": "eq", "value": "customer" },
        { "type": "metadata", "field": "region", "operator": "in", "value": ["us-west", "us-east"] }
      ]
    }
  }'

Archive a segment

DELETE https://api.molted.email/v1/segments/:id

curl

curl -X DELETE https://api.molted.email/v1/segments/SEGMENT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Compute segment membership

Trigger an async computation of the segment's current members.

POST https://api.molted.email/v1/segments/:id/compute

curl

curl -X POST https://api.molted.email/v1/segments/SEGMENT_ID/compute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tenantId": "tenant_abc123" }'

Each computation creates a point-in-time snapshot of matching contacts.

List segment members

GET https://api.molted.email/v1/segments/:id/members

curl

curl "https://api.molted.email/v1/segments/SEGMENT_ID/members?tenantId=tenant_abc123&limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Results are paginated. Use limit and offset to page through members.

Filter types

Type	Description	Example fields
`contact_field`	Filter on contact properties.	`email`, `name`, `ownerEmail`, `lifecycleStage`, `dealStage`
`account_field`	Filter on the contact's account.	`name`, `domain`
`metadata`	Filter on contact metadata keys.	Any key in the contact's `metadata` object.
`firmographic`	Filter on account metadata keys.	Any key in the account's `metadata` object.
`behavioral`	Filter on event counts within a time window.	`event`, `threshold`, `timeWindowDays` (max 90 days)

Operators

Operator	Description
`eq`	Equals
`neq`	Not equals
`gt`	Greater than
`gte`	Greater than or equal
`lt`	Less than
`lte`	Less than or equal
`contains`	String contains
`not_contains`	String does not contain
`in`	Value is in list
`not_in`	Value is not in list
`exists`	Field exists and is not null
`not_exists`	Field does not exist or is null
`between`	Value is between two bounds

Nested logic

Filter groups can contain other filter groups for complex AND/OR logic:

Nested filter group

{
  "logic": "or",
  "filters": [
    {
      "logic": "and",
      "filters": [
        { "type": "contact_field", "field": "lifecycleStage", "operator": "eq", "value": "lead" },
        { "type": "behavioral", "event": "email_opened", "operator": "gte", "threshold": 3, "timeWindowDays": 30 }
      ]
    },
    {
      "logic": "and",
      "filters": [
        { "type": "contact_field", "field": "lifecycleStage", "operator": "eq", "value": "customer" },
        { "type": "metadata", "field": "plan", "operator": "eq", "value": "enterprise" }
      ]
    }
  ]
}

This matches contacts who are either (leads with 3+ email opens in the last 30 days) OR (enterprise customers).

On this page