Mail API reference

Mail API · Segments

post/v1/workspaces/{workspace_id}/contacts/{contact}/segments/{segment_id}Auth

Add a contact to a static segment

Adds the contact. Adding a contact that is already a member changes nothing and answers the same way, with `added_at` from the first time.

Path parameters

workspace_id*string · uuid

Id of the workspace.

contact*string

The contact id, or its email address (URL-encoded).

segment_id*string · uuid

Id of the segment.

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`.

Response · 201 The contact is a member (added now, or already).

segment_id*string · uuid

The segment the contact was added to.

contact_id*string · uuid

The contact that was added.

added_at*string · date-time

When the contact was added (the first time, if it was added twice).

Example

Request

POST https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/contacts/{contact}/segments/{segment_id}
Authorization: Bearer YOUR_TOKEN

Response

{
  "segment_id": "00000000-0000-0000-0000-000000000000",
  "contact_id": "00000000-0000-0000-0000-000000000000",
  "added_at": "2026-01-01T00:00:00.000Z"
}