Create segment

If you have questions regarding this API, please visit our API FAQ page.

Creating a segment

Make a POST request to https://webapi.inboxroad.com/api/v2/segments/ with a valid X-API-Key.

curl -X POST 'https://webapi.inboxroad.com/api/v2/segments/' \
  -H 'X-API-Key: <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Active Gmail Subscribers",
    "color": "#7cb7de",
    "contact_list_ids": ["0fd3d5b4-1c0a-4e91-8a4f-0f17dc6dc5ab"],
    "rules_json": {
      "any": [
        {
          "all": [
            { "kind": "field", "field": "status", "operator": "equals", "value": "subscribed" },
            { "kind": "activity", "metric": "open", "operator": "count_gte", "value": 1,
              "days_window": { "mode": "last", "days": 30 } }
          ]
        }
      ]
    }
  }'

Request fields

Field name	Required	Description
name	Yes	Name of the segment.
color	Yes	Hex color from the allowed palette.
contact_list_ids	Yes	One or more contact list ids (UUIDs) the segment draws from. At least one.
rules_json	Yes	The segment definition. See Segment rules below.
description	No	Optional description.

Segment rules

rules_json is a nested boolean expression:

{ "any": [ { "all": [ <condition>, ... ] }, ... ] }

• any is a list of rule groups combined with OR.
• Each group’s all is a list of conditions combined with AND.

Each condition is an object with a kind discriminator. The available kinds:

field — match a contact field

{ "kind": "field", "field": "<column_name>", "operator": "<op>", "value": <value> }

field is a contact column (see Get contact list for valid columns). Operators: equals, not_equals, contains, not_contains, starts_with, in, not_in, is_null, is_not_null, gt, gte, lt, lte, has_any, has_all, has_none. (Available operators depend on the field’s data type; is_null / is_not_null take no value.)

activity — open / click activity

{ "kind": "activity", "metric": "open", "operator": "count_gte", "value": 1,
  "days_window": { "mode": "last", "days": 30 },
  "include_campaign_ids": [], "exclude_campaign_ids": [] }

• metric: open or click.
• operator: ever, never, count_gte, count_lte, count_eq. value is required (and ≥ 0) for the count_* operators and must be omitted for ever / never.
• days_window (optional): { "mode": "last" | "more_than", "days": <int > 0> }.
• include_campaign_ids / exclude_campaign_ids (optional): cannot be used together.

membership — membership in other lists

{ "kind": "membership", "operator": "in", "list_ids": ["<uuid>", ...] }

operator: in or not_in. list_ids requires at least one UUID.

deliverability — bounce / complaint / delivery activity

{ "kind": "deliverability", "metric": "bounce", "operator": "count_gte", "value": 1,
  "days_window": { "mode": "last", "days": 90 } }

• metric: bounce, complaint, delivered, unsubscribe.
• operator: ever, count_gte, count_lte, count_eq. value is required for count_* and omitted for ever.

isp — recipient ISP

{ "kind": "isp", "operator": "in", "values": [1, 2] }

operator: in or not_in. values is a list of ISP alias ids.

Response

The build starts immediately, so the returned segment begins in status PENDING and transitions to DONE once total_count is known. The response shape matches Get segment.

{
  "id": "92a6ef72-c74e-4e37-bd84-9e8fbb83fef4",
  "name": "Active Gmail Subscribers",
  "color": "#7cb7de",
  "description": null,
  "rules_json": { "any": [ { "all": [ /* ... */ ] } ] },
  "contact_list_ids": ["0fd3d5b4-1c0a-4e91-8a4f-0f17dc6dc5ab"],
  "status": "PENDING",
  "total_count": null,
  "created_at": "2026-05-21T11:30:00Z",
  "updated_at": "2026-05-21T11:30:00Z",
  "display_fields": []
}

Possible response codes

Status code	Description
200	Segment created successfully (build started).
400	Invalid request data (e.g. malformed rules_json, missing required field, or color not in the palette).
401	Unauthorized.