Segments

Dynamic contact filters, expressed as a condition tree over contact fields and properties.

Create a segment

POST

/segments

Authorizations

Authorization

string

header

required

API key for your workspace, scoped to contacts:manage. Pass it as a Bearer token in the Authorization header.

Body · application/json

name

string

filters

object

Create a segment

curl https://api.mailcraft.host/v1/segments \
  -X POST \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Pro plan, subscribed",
    "filters": {
      "operator": "and",
      "conditions": [
        { "field": "status", "operator": "eq", "value": "subscribed" },
        { "field": "properties.plan", "operator": "eq", "value": "pro" }
      ]
    }
  }'

{
  "data": {
    "id": 6,
    "name": "Pro plan, subscribed",
    "description": null,
    "filters": {
      "operator": "and",
      "conditions": [
        { "field": "status", "operator": "eq", "value": "subscribed" },
        { "field": "properties.plan", "operator": "eq", "value": "pro" }
      ]
    },
    "contact_count": null,
    "created_at": "2026-09-22T14:22:00.000000Z"
  }
}

List segments

GET

/segments

Authorizations

Authorization

string

header

required

API key for your workspace, scoped to contacts:manage. Pass it as a Bearer token in the Authorization header.

List segments

curl https://api.mailcraft.host/v1/segments \
  -H 'Authorization: Bearer sk_live_...'

{
  "data": [
    { "id": 6, "name": "Pro plan, subscribed", "contact_count": 214 }
  ]
}

Get a segment

GET

/segments/{segment}

Authorizations

Authorization

string

header

required

API key for your workspace, scoped to contacts:manage. Pass it as a Bearer token in the Authorization header.

Get a segment

curl https://api.mailcraft.host/v1/segments/6 \
  -H 'Authorization: Bearer sk_live_...'

{
  "data": {
    "id": 6,
    "name": "Pro plan, subscribed",
    "filters": {
      "operator": "and",
      "conditions": [
        { "field": "status", "operator": "eq", "value": "subscribed" },
        { "field": "properties.plan", "operator": "eq", "value": "pro" }
      ]
    },
    "contact_count": 214,
    "created_at": "2026-09-22T14:22:00.000000Z"
  }
}

Delete a segment

DELETE

/segments/{segment}

Authorizations

Authorization

string

header

required

API key for your workspace, scoped to contacts:manage. Pass it as a Bearer token in the Authorization header.

Delete a segment

curl https://api.mailcraft.host/v1/segments/6 \
  -X DELETE \
  -H 'Authorization: Bearer sk_live_...'

(empty body)