Segments

Segments are groups of contacts used for targeting broadcasts and workflow triggers. A contact can belong to multiple segments.

Create a segment

POST
/v1/segments

Create a new segment.

Request body

ParameterTypeDescription
namerequiredstringDisplay name for the segment.
cURL
curl -X POST https://api.txtly.com.au/v1/segments \
  -H "Authorization: Bearer tx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "VIP Customers"}'
Response — 201 Created
{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "name": "VIP Customers",
  "contactCount": 0,
  "unsubscribedCount": 0,
  "createdAt": "2026-03-21T00:00:00Z"
}

List segments

GET
/v1/segments

List all segments for the current team.

Example Response
{
  "data": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "name": "VIP Customers",
      "contactCount": 42,
      "unsubscribedCount": 3,
      "createdAt": "2026-03-21T00:00:00Z"
    }
  ]
}

Get a segment

GET
/v1/segments/{id}

Retrieve a segment by ID including contact and unsubscribed counts.

Example Response
{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "name": "VIP Customers",
  "contactCount": 42,
  "unsubscribedCount": 3,
  "createdAt": "2026-03-21T00:00:00Z"
}

Update a segment

PATCH
/v1/segments/{id}

Update the segment name.

Request body

ParameterTypeDescription
namerequiredstringNew display name for the segment.
cURL
curl -X PATCH https://api.txtly.com.au/v1/segments/d290f1ee-... \
  -H "Authorization: Bearer tx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Premium Customers"}'
Example Response
{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "name": "Premium Customers",
  "contactCount": 42,
  "unsubscribedCount": 3,
  "createdAt": "2026-03-21T00:00:00Z"
}

Delete a segment

DELETE
/v1/segments/{id}

Delete a segment. Contacts in the segment are not deleted.

Add contacts to a segment

POST
/v1/segments/{id}/contacts

Add one or more contacts to a segment.

Request body

ParameterTypeDescription
contactIdsrequiredstring[]Array of contact IDs to add to the segment.
cURL
curl -X POST https://api.txtly.com.au/v1/segments/d290f1ee-.../contacts \
  -H "Authorization: Bearer tx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"contactIds": ["a1b2c3d4-5e6f-7890-abcd-ef1234567890"]}'

Remove a contact from a segment

DELETE
/v1/segments/{id}/contacts/{contactId}

Remove a specific contact from a segment.