Mail API reference

Mail API · Segments

post/v1/workspaces/{workspace_id}/segmentsAuth

Create a segment

Without `rule`, a static segment: add and remove contacts one at a time. With `rule`, a rule segment: its members are the contacts whose fields and properties match, evaluated every time it is read. At most 100 segments per workspace.

Path parameters

workspace_id*string · uuid

Id of the workspace.

Headers

Idempotency-Keystring

Opaque client-generated string (1–256 chars, `[A-Za-z0-9._:-]`) used to deduplicate retries within a 24h window. A retry with the same key and body returns the original response with `Idempotent-Replay: true`.

Request body

name*string

Unique per workspace.

Example: "Pro customers"

descriptionstring

Optional description of who is in the segment.

Example: "Everyone on the pro plan"

ruleobject

Omit for a static segment (add contacts with `POST .../contacts/{contact}/segments/{segment_id}`). Set it for a rule segment: its members are the contacts that match, evaluated whenever the segment is read. The type is fixed once created.

Response · 201

id*string · uuid

The segment id.

name*string

Name of the segment.

Example: "Pro customers"

description*string

Optional description of who is in the segment.

type*object

`static`: an explicit member list. `rule`: the contacts matching `rule`.

rule*object

Null for a static segment.

created_at*string · date-time

When the segment was created.

updated_at*string · date-time

When the segment was last changed.

Example

Request

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

{
  "name": "Pro customers",
  "description": "Everyone on the pro plan",
  "rule": {}
}

Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "Pro customers",
  "description": "string",
  "type": {},
  "rule": {},
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}