Create and manage audience segments with dynamic filter criteria for targeted campaigns

Segments let you group contacts by shared characteristics using filter rules. Dynamic segments automatically recalculate membership as contact data changes.

Authentication

Requires an API key with the contacts scope, or an active session. Pass Authorization: Bearer msk_.... Base URL: https://api.misar.io/mail.

Endpoints

Method	Path	Description
`GET`	`/v1/segments`	List segments
`POST`	`/v1/segments`	Create segment
`GET`	`/v1/segments/:id`	Get segment
`PATCH`	`/v1/segments/:id`	Update segment
`DELETE`	`/v1/segments/:id`	Delete segment
`GET`	`/v1/segments/:id/preview`	Preview matching contacts
`POST`	`/v1/segments/:id/refresh`	Recalculate membership

Filter criteria

Each segment uses a filter_criteria object with a top-level operator and an array of rules.

{
  "operator": "AND",
  "rules": [
    {
      "field": "status",
      "operator": "equals",
      "value": "subscribed"
    },
    {
      "field": "created_at",
      "operator": "after",
      "value": "2026-01-01"
    },
    {
      "field": "tags",
      "operator": "contains",
      "value": "early-adopter"
    }
  ]
}

Supported operators per field:

Operator	Description
`equals` / `not_equals`	Exact match
`contains` / `not_contains`	Substring or array membership
`starts_with` / `ends_with`	String prefix/suffix
`greater_than` / `less_than`	Numeric or date comparison
`before` / `after`	Date comparison
`is_empty` / `is_not_empty`	Null/blank check
`in` / `not_in`	Match against a list of values

List segments

GET/mail/v1/segments

List segments with pagination.

Query parameters

pageintegerquerydefault: 1

Page number.

limitintegerquerydefault: 20

Results per page (max 100).

Response fields

successboolean

true when the request succeeded.

dataobject

Contains segments (the page of segments) and pagination metadata (page, limit, total, total_pages). Each segment includes id, name, description, segment_type, contact_count, last_calculated_at, and created_at.

curl https://api.misar.io/mail/v1/segments \
  -H "Authorization: Bearer msk_..."

const res = await fetch("https://api.misar.io/mail/v1/segments?page=1&limit=20", {
  headers: { Authorization: "Bearer msk_..." },
});
const { data } = await res.json();

{
  "success": true,
  "data": {
    "segments": [
      {
        "id": "seg_01hvxyz",
        "name": "Active subscribers — Q1 2026",
        "description": "Subscribed after Jan 1 with early-adopter tag",
        "segment_type": "dynamic",
        "contact_count": 1842,
        "last_calculated_at": "2026-05-27T10:00:00Z",
        "created_at": "2026-03-15T08:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 7,
      "total_pages": 1
    }
  }
}

Create a segment

POST/mail/v1/segments

Create a segment. The segment is evaluated immediately on creation — contact_count and last_calculated_at are populated in the response.

Request body

namestringbodyrequired

1–200 characters.

descriptionstringbody

Max 1000 characters.

segment_typedynamic | staticbodyrequired

Dynamic re-evaluates on refresh; static is manually managed.

filter_criteriaobjectbodyrequired

{ operator, rules }.

Response fields

successboolean

true when the segment was created.

dataobject

The created segment, including id, name, segment_type, filter_criteria, contact_count, last_calculated_at, created_at, and updated_at.

curl -X POST https://api.misar.io/mail/v1/segments \
  -H "Authorization: Bearer msk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Active subscribers — Q1 2026",
    "description": "Subscribed after Jan 1 with early-adopter tag",
    "segment_type": "dynamic",
    "filter_criteria": {
      "operator": "AND",
      "rules": [
        { "field": "status", "operator": "equals", "value": "subscribed" },
        { "field": "created_at", "operator": "after", "value": "2026-01-01" },
        { "field": "tags", "operator": "contains", "value": "early-adopter" }
      ]
    }
  }'

const res = await fetch("https://api.misar.io/mail/v1/segments", {
  method: "POST",
  headers: {
    Authorization: "Bearer msk_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Active subscribers — Q1 2026",
    segment_type: "dynamic",
    filter_criteria: {
      operator: "AND",
      rules: [
        { field: "status", operator: "equals", value: "subscribed" },
        { field: "created_at", operator: "after", value: "2026-01-01" },
        { field: "tags", operator: "contains", value: "early-adopter" },
      ],
    },
  }),
});
const { data } = await res.json();

{
  "success": true,
  "data": {
    "id": "seg_01hvxyz",
    "name": "Active subscribers — Q1 2026",
    "segment_type": "dynamic",
    "filter_criteria": {
      "operator": "AND",
      "rules": [...]
    },
    "contact_count": 1842,
    "last_calculated_at": "2026-05-27T10:01:44Z",
    "created_at": "2026-05-27T10:01:44Z",
    "updated_at": "2026-05-27T10:01:44Z"
  }
}

Get a segment

GET/mail/v1/segments/:id

Returns the full segment object including filter_criteria and current contact_count.

Path parameters

idstringpathrequired

ID of the segment to retrieve.

Response fields

successboolean

true when the request succeeded.

dataobject

The full segment object, including filter_criteria and current contact_count.

curl https://api.misar.io/mail/v1/segments/seg_01hvxyz \
  -H "Authorization: Bearer msk_..."

Update a segment

PATCH/mail/v1/segments/:id

Send only the fields to change. Updating filter_criteria triggers an immediate re-evaluation.

Path parameters

idstringpathrequired

ID of the segment to update.

Request body

namestringbody

1–200 characters.

descriptionstringbody

Max 1000 characters.

segment_typedynamic | staticbody

Dynamic re-evaluates on refresh; static is manually managed.

filter_criteriaobjectbody

{ operator, rules }. Updating this triggers an immediate re-evaluation.

curl -X PATCH https://api.misar.io/mail/v1/segments/seg_01hvxyz \
  -H "Authorization: Bearer msk_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Active subscribers — updated" }'

Delete a segment

DELETE/mail/v1/segments/:id

Permanently delete a segment. Deleting a segment does not delete the contacts in it.

Path parameters

idstringpathrequired

ID of the segment to delete.

Response fields

successboolean

true when the segment was deleted.

{ "success": true }

Preview segment contacts

GET/mail/v1/segments/:id/preview

Returns a sample of contacts that currently match the segment criteria without persisting any changes.

Path parameters

idstringpathrequired

ID of the segment to preview.

Response fields

successboolean

true when the request succeeded.

dataobject

Contains contacts (a sample of matching contacts) and total_matching (the total count of matching contacts).

{
  "success": true,
  "data": {
    "contacts": [...],
    "total_matching": 1842
  }
}

Refresh a segment

POST/mail/v1/segments/:id/refresh

Recalculates dynamic segment membership against the latest contact data. Returns the updated contact_count.

Path parameters

idstringpathrequired

ID of the segment to refresh.

Response fields

successboolean

true when the recalculation completed.

dataobject

Contains the updated contact_count and last_calculated_at.

{
  "success": true,
  "data": {
    "contact_count": 1901,
    "last_calculated_at": "2026-05-27T11:00:00Z"
  }
}

Dynamic segments refresh automatically on a schedule. Use the refresh endpoint to force an immediate recalculation before sending a campaign.