Add a member

Add a member

POST/api/v1/segments/{id}/contacts

POST /segments/{id}/contacts
curl -X POST 'https://www.unitpost.com/api/v1/segments/seg_123/contacts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "contact": "customer@example.com"
  }'
Response · 200
{
  "object": "list",
  "data": [
    {
      "object": "segment_member",
      "contact_id": "contact_123",
      "subscribed": false,
      "unsubscribed_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "has_more": false,
  "added": 0
}

Add a contact to a static segment, referenced by contact id or email (contact), or many at once: contact_ids or emails, up to 1,000 in one call. Send exactly one of the three. The operation is idempotent — adding a contact that's already a member is a no-op that keeps its per-segment subscription and still succeeds. Each contact that joins gets a segment.joined webhook and an activity row. A list is checked first: the first contact that isn't one of yours is a 404 naming it (details), and nobody is added. One contact answers 201 with its membership; a list answers 200 with each listed contact's membership in the order sent and added, how many joined now. Adding a list counts against a limit of 30 bulk contact edits a minute per workspace by default (a 429 added nobody; retry after Retry-After). For more than 1,000 contacts, call it once per 1,000. See the current members with List segment members. Requires the segments:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body4 fields
FieldTypeDescription
contactstringOne contact: its id (`con_…`) or email.
contact_idsstring[]Many contacts of this workspace by id (`con_…`), up to 1,000.
emailsstring[]Many contacts of this workspace by email address, up to 1,000.
subscribedbooleanA new member's per-segment subscription (default true). A contact that is already a member keeps its own.
Response · 200 fields4 fields
FieldTypeDescription
objectrequiredstring—
contact_idrequiredstring—
subscribedrequiredboolean—
unsubscribed_atrequiredstring | null—
200201401404422429

Search docs and guides

Search the docs and product guides.