Resources

Segments API

List, create, update and delete segments built from profile, email, website and store behavior.

How segments work

A segment is a saved, dynamic filter on a list: "customers who placed an order in the last 90 days", "subscribers who have not opened anything in 6 months". Membership is calculated from the segment's criteria and updates as subscribers' data and behavior change - you never add people to a segment manually. Campaigns can target a segment directly via recipient_type: "segment".

Rules can reference four kinds of data: profile properties (status, tags, custom fields, signup date), email activity (opens, clicks, engagement score), website behavior from the tracking snippet (viewed product, page visits) and store behavior from a connected Shopify or WooCommerce store (placed order, revenue, ordered product).

Use cases

Create a VIP segment (high revenue, recent orders) from your own analytics pipeline.
Build a re-engagement segment of subscribers with no opens in X days and target it with a win-back campaign.
Maintain compliance segments, for example everyone whose double opt-in is still pending.
Recalculate a segment on demand and read its subscriber count for reporting.

The criteria object

criteria contains a top-level logic (AND or OR) and a list of rules. Each rule has:

Name	Type	Description
`field`	string	What to evaluate, for example status, tags, placed_order, order_revenue, viewed_product, campaign_opens or last_website_visit_at.
`operator`	string	How to compare. Depends on the field type: equals/contains/starts_with for text, before/after/between/days_ago for dates, at_least_once/zero_times/at_least for behaviors, greater_than for numbers.
`value`	string	The comparison value. For behavioral count operators (at_least, at_most, exactly) this is the number of times.
`value2`	string	Second value for between ranges. For behavior, revenue and product fields it is the optional time window in days (empty = over all time).
`connector`	string	AND or OR - how this rule connects to the previous one.

For example, "placed an order at least once in the last 90 days AND has the vip tag":

criteria

{
  "logic": "AND",
  "rules": [
    { "field": "placed_order", "operator": "at_least_once", "value": "", "value2": "90" },
    { "field": "tags", "operator": "contains", "value": "vip", "connector": "AND" }
  ]
}

Build criteria in the app first

The segment builder in the app uses exactly this structure. The easiest way to learn the shape of a rule is to build the segment in the dashboard, then fetch it via the API and copy the criteria.

Endpoints

GET

Get segments

/segments-api

Retrieve all segments with subscriber counts. Supports page, limit (max 100), status and search query parameters.

Name	Type	Description
`page`	number	Page number.
`limit`	number	Results per page (max 100).
`status`	string	Filter by status.
`search`	string	Search segments.

curl -X GET "https://api.mailingplatform.net/segments-api" \
  -H "Authorization: Bearer mp_live_..."

GET

Get single segment

/segments-api/{segmentId}

Retrieve one segment by id. Returns 404 NOT_FOUND if the segment does not exist or belongs to another account.

curl -X GET "https://api.mailingplatform.net/segments-api/{segmentId}" \
  -H "Authorization: Bearer mp_live_..."

POST

Create segment

/segments-api

Create a segment on a list. name, criteria and list_id are required.

Request body

Name	Type	Description
`name`required	string	Segment name.
`criteria`required	object	Match logic and rules.
`list_id`required	string	List the segment is built on.
`description`	string	Optional description.
`status`	string	Segment status, for example active.

curl -X POST "https://api.mailingplatform.net/segments-api" \
  -H "Authorization: Bearer mp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Active Buyers",
  "description": "Optional description",
  "list_id": "list-123",
  "status": "active",
  "criteria": {
    "logic": "AND",
    "rules": [
      { "field": "status", "operator": "equals", "value": "active" }
    ]
  }
}'

PUT

Update segment

/segments-api/{segmentId}

Update name, description, criteria or status. Other fields are ignored.

curl -X PUT "https://api.mailingplatform.net/segments-api/{segmentId}" \
  -H "Authorization: Bearer mp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"...","description":"...","criteria":{},"status":"active"}'

DELETE

Delete segment

/segments-api/{segmentId}

Permanently delete a segment. Subscribers on the underlying list are not affected.

curl -X DELETE "https://api.mailingplatform.net/segments-api/{segmentId}" \
  -H "Authorization: Bearer mp_live_..."

POST

Recalculate segment

/calculate-segment/{segmentId}

Recalculates membership for a saved segment and returns the updated subscriber count. Useful after changing criteria or importing subscribers, when you want the count refreshed immediately instead of waiting for the next automatic calculation.

Name	Type	Description
`segmentId`required	string	Segment id (path). The segment must already exist.

Requires a user session token

Unlike the other endpoints on this page, recalculation currently only accepts a Supabase user JWT as the Bearer token, not an mp_live_ API key.

curl -X POST "https://api.mailingplatform.net/calculate-segment/{segmentId}" \
  -H "Authorization: Bearer <user-jwt>"