Mail API reference

Mail API · Segments

post/v1/workspaces/{workspace_id}/segments/previewAuth

Preview a segment rule

Counts the contacts a rule selects and returns the newest few, without saving anything.

Path parameters

workspace_id*string · uuid

Id of the workspace.

Request body

rule*object
match*object

`all`: every condition must hold (AND). `any`: at least one (OR).

conditions*array

The conditions; a contact matches when it meets all of them.

Response · 200

metrics*object
segment_id*string · uuid

Null on a preview.

contact_count*number

Contacts in the segment now.

Example: 1240

unsubscribed_count*number

Of those, globally unsubscribed.

Example: 31

unsubscribed_share*number

`unsubscribed_count / contact_count`, 0 to 1 (4 decimals); 0 for an empty segment.

Example: 0.025

consented_count*number

Of those, with a recorded marketing consent.

Example: 1100

computed_at*string · date-time

When the counts were taken (rule segments change as contacts do).

sample*array

Up to 5 matching contacts, newest first.

Example

Request

POST https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/segments/preview
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "rule": {
    "match": {},
    "conditions": [
      {
        "field": "plan",
        "operator": {},
        "value": "pro"
      }
    ]
  }
}

Response

{
  "metrics": {
    "segment_id": "00000000-0000-0000-0000-000000000000",
    "contact_count": 1240,
    "unsubscribed_count": 31,
    "unsubscribed_share": 0.025,
    "consented_count": 1100,
    "computed_at": "2026-01-01T00:00:00.000Z"
  },
  "sample": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "email": "ada@example.com",
      "first_name": "string",
      "last_name": "string",
      "unsubscribed": false,
      "unsubscribed_at": "2026-01-01T00:00:00.000Z",
      "properties": {
        "company": "Acme"
      },
      "consented_at": "2026-01-01T00:00:00.000Z",
      "consent_source": "signup-form-2026",
      "created_via": {},
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}