/v1/workspaces/{workspace_id}/segmentsAuthCreate 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 · uuidId of the workspace.
Headers
Idempotency-KeystringOpaque 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*stringUnique per workspace.
Example: "Pro customers"
descriptionstringOptional description of who is in the segment.
Example: "Everyone on the pro plan"
ruleobjectOmit 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 · uuidThe segment id.
name*stringName of the segment.
Example: "Pro customers"
description*stringOptional description of who is in the segment.
type*object`static`: an explicit member list. `rule`: the contacts matching `rule`.
rule*objectNull for a static segment.
created_at*string · date-timeWhen the segment was created.
updated_at*string · date-timeWhen 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"
}