Create Segment

Create a segment from a name and a filter tree.

Request

POST /segments

Request Body

Parameter	Type	Required	Description
name	string	Yes	Segment name (max 255 characters). Must contain a non-whitespace character. Names do not have to be unique.
filters	object	Yes	Filter tree. filters.root must be a group. See Filters for the size and nesting limits.
filters.root.type	string	Yes	group
filters.root.operator	string	Yes	AND or OR
filters.root.conditions	array	Yes	Conditions and nested groups. An empty array is valid — see Filter group.

Each condition in filters.root.conditions:

Parameter	Type	Required	Description
type	string	Yes	condition
fieldKey	string	Yes	A built-in field, or a custom field key on the account. See Filters.
operator	string	Yes	An operator that field allows. See Filter condition.
kind	string	Yes	property, custom_field, campaign_activity, list_membership, or automation_activity, matching the field.
modelId	string|null	Conditional	Required UUID for as:one_time_product. Optional on any other custom field. See One-time product and Custom fields.
value	string|number|boolean|null	Conditional	Comparison value, or the UUID of a list, campaign, or automation on the account when the field requires one. Required with every operator except exists, not_exists, is_empty, and is_not_empty — see Filter condition. The response includes it, null when omitted.
withinDays	integer|null	No	Positive number of days on campaign-activity and automation-activity fields. See Filter condition.

Example Requests

A one-time product purchase:

curl -X POST "https://email.easy.tools/api/v1/segments" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Purchased the starter kit",
    "filters": {
      "root": {
        "type": "group",
        "operator": "AND",
        "conditions": [
          {
            "type": "condition",
            "fieldKey": "as:one_time_product",
            "operator": "exists",
            "kind": "custom_field",
            "modelId": "76d3d4e2-54a7-48de-b40e-1dcfc9505a0f",
            "value": null
          }
        ]
      }
    }
  }'

List membership. value is the list UUID:

curl -X POST "https://email.easy.tools/api/v1/segments" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Newsletter subscribers",
    "filters": {
      "root": {
        "type": "group",
        "operator": "AND",
        "conditions": [
          {
            "type": "condition",
            "fieldKey": "contact_list",
            "operator": "exists",
            "kind": "list_membership",
            "value": "70dbd819-fac2-4dcf-b655-fb925e24410b"
          }
        ]
      }
    }
  }'

Response

Success Response (201 Created)

A one-time product condition:

{
  "data": {
    "uuid": "e16abec3-444d-4512-9a57-17ced5ad51b2",
    "name": "Purchased the starter kit",
    "contacts_count": 0,
    "contacts_count_calculated_at": null,
    "filters": {
      "root": {
        "type": "group",
        "operator": "AND",
        "conditions": [
          {
            "type": "condition",
            "fieldKey": "as:one_time_product",
            "operator": "exists",
            "value": null,
            "kind": "custom_field",
            "modelId": "76d3d4e2-54a7-48de-b40e-1dcfc9505a0f",
            "withinDays": null
          }
        ]
      }
    },
    "created_at": "2026-09-12T16:04:27Z",
    "updated_at": "2026-09-12T16:04:27Z"
  }
}

List membership:

{
  "data": {
    "uuid": "404e63c7-3d13-44cc-b968-bf2ae2867426",
    "name": "Newsletter subscribers",
    "contacts_count": 0,
    "contacts_count_calculated_at": null,
    "filters": {
      "root": {
        "type": "group",
        "operator": "AND",
        "conditions": [
          {
            "type": "condition",
            "fieldKey": "contact_list",
            "operator": "exists",
            "value": "70dbd819-fac2-4dcf-b655-fb925e24410b",
            "kind": "list_membership",
            "modelId": null,
            "withinDays": null
          }
        ]
      }
    },
    "created_at": "2026-09-30T14:22:08Z",
    "updated_at": "2026-09-30T14:22:08Z"
  }
}

Response Fields

The created segment has the fields described in Segment Object. contacts_count is 0 and contacts_count_calculated_at is null until the cached size has been calculated — see Audience size. The live count is List Segment Contacts.

Error Responses

Validation Error (422 Unprocessable Entity)

Returned when name or filters is invalid. details is keyed by field name. Filter failures are listed in details.filters. The message below is a fieldKey the account does not have — see One-time product. The other filter messages are under Filters.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid",
    "details": {
      "filters": ["Unknown filter field 'as:one_time_product'."]
    }
  }
}