Segmentation

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 to target experiments (segmentId). Journeys don't read segments: journey trigger conditions and branch conditions only look at the trigger event's payload.

On api.molted.email, pass tenantId (in the body for writes, in the query string for reads); without it a key call fails with 401 missing_tenant_id. mailbox.molted.email, the CLI and the MCP server fill it in. Writes need manage scope and refuse a mailbox-scoped key.

Create a segment

molted segments create \
  --name "Enterprise customers in US" \
  --filters '{
    "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 }
    ]
  }'

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

curl -X POST https://mailbox.molted.email/v1/segments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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 }
      ]
    }
  }'

Get a segment

molted segments get seg_abc123

GET https://mailbox.molted.email/v1/segments/:id

curl "https://mailbox.molted.email/v1/segments/seg_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get also returns archived segments, and adds computeDurationMs. An unknown id is 404 segment_not_found.

List segments

molted segments list

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

curl "https://mailbox.molted.email/v1/segments" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Returns an array of active segments. Archived segments are excluded. contactCount and snapshotVersion are null until the segment's first compute (creating a segment doesn't compute it).

[
  {
    "id": "seg_abc123",
    "tenantId": "tenant_abc123",
    "name": "Enterprise customers in US",
    "filterGroup": { "logic": "and", "filters": [ "..." ] },
    "status": "active",
    "contactCount": 142,
    "snapshotVersion": 3,
    "createdAt": "2026-03-01T12:00:00Z",
    "updatedAt": "2026-03-15T08:30:00Z"
  }
]

If you have no segments yet, the response is an empty array:

[]

Update a segment

molted segments update seg_abc123 \
  --name "Enterprise US (updated)" \
  --filters '{
    "logic": "and",
    "filters": [
      { "type": "contact_field", "field": "lifecycleStage", "operator": "eq", "value": "customer" },
      { "type": "metadata", "field": "region", "operator": "in", "value": ["us-west", "us-east"] }
    ]
  }'

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

curl -X PATCH https://mailbox.molted.email/v1/segments/seg_abc123 \
  -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

molted segments archive seg_abc123

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

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

Archiving is a soft delete: it returns { "archived": true } (or 404), and the segment stays readable with get.

Compute segment membership

Trigger an async recomputation of the segment's current members. Each computation creates a point-in-time snapshot of matching contacts.

Most flows do not need to call this directly: contacts sync automatically enqueues a recompute for every active segment in the tenant, so segments list / segments get reflect the new contacts shortly after the sync. Use this command when you want to force a refresh without syncing contacts (e.g., after manually editing contact metadata, or to verify a freshly created segment).

Create and update already store the canonical { logic, filters, type, operator } shape. Compute still rewrites a legacy filter_group shape (e.g. { operator, conditions, op } from older API versions) to the canonical one, as a safety net for rows written before that change.

The compute call returns { "queued": true, "segmentId": "..." }.

molted segments compute seg_abc123

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

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

List segment members

Results are paginated. Use limit and offset to page through members. Each member is { id, email, name, lifecycleStage, dealStage }, ordered by email.

molted segments members seg_abc123 --limit 50 --offset 0

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

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

Get contact segments

List all segments a contact belongs to. This is a reverse lookup -- given a contact, it returns every segment they are a member of.

To check whether a contact is in one specific segment instead, use analytics segment-check.

Returns [{ id, name, status }] for active segments only, or 404 contact_not_found.

molted segments contact con_abc123

GET https://mailbox.molted.email/v1/segments/contact/:contactId/segments

curl "https://mailbox.molted.email/v1/segments/contact/con_abc123/segments" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filter types

Each filter has a type that determines which fields you can query.

Standard filter structure

{
  "type": "contact_field",
  "field": "lifecycleStage",
  "operator": "eq",
  "value": "customer"
}

Behavioral filters

Behavioral filters count how many times an event occurred within a time window. They use a behavioralWindow object instead of a simple value.

{
  "type": "behavioral",
  "field": "event_count",
  "operator": "gte",
  "value": 0,
  "behavioralWindow": {
    "eventName": "email_opened",
    "windowDays": 30,
    "countOperator": "gte",
    "countValue": 3
  }
}

This example matches contacts with 3 or more email_opened events in the window.

Operators

Type constraints: gt, gte, lt, lte, and between only work with numeric values. contains and not_contains only work with strings. Using an operator with the wrong value type returns no matches.

Filter group structure

A filter group wraps one or more filters with a logic operator.

{
  "logic": "and",
  "filters": [
    { "type": "contact_field", "field": "lifecycleStage", "operator": "eq", "value": "customer" },
    { "type": "metadata", "field": "region", "operator": "eq", "value": "us-west" }
  ]
}

Nested logic

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

{
  "logic": "or",
  "filters": [
    {
      "logic": "and",
      "filters": [
        { "type": "contact_field", "field": "lifecycleStage", "operator": "eq", "value": "lead" },
        {
          "type": "behavioral",
          "field": "event_count",
          "operator": "gte",
          "value": 0,
          "behavioralWindow": {
            "eventName": "email_opened",
            "windowDays": 30,
            "countOperator": "gte",
            "countValue": 3
          }
        }
      ]
    },
    {
      "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). Nesting depth is unlimited.

Related

• Contacts - manage the contacts that segments filter on
• Analytics - check segment membership with segment-check
• Experimentation - target an experiment at a segment with segmentId

MCP tools

The segment tools are in the opt-in journeys toolset (see MCP server):

There is no list tool; read the molted://segments resource instead.