Contacts

Manage contacts in your Txtly account with full CRUD operations.

Create Contact

POST

/v1/contacts

Create a new contact. Email must be unique within your team.

Parameters

Parameter	Type	Description
`email`required	`string`	Email address (unique per team)
`firstName`	`string`	First name
`lastName`	`string`	Last name
`phoneNumber`	`string`	Phone number in E.164 format (e.g. +61412345678)
`properties`	`object`	Custom JSON properties

Example Request

curl -X POST https://api.txtly.com.au/v1/contacts \
  -H "Authorization: Bearer tx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "+61412345678",
    "properties": {
      "company": "Acme Corp",
      "plan": "premium"
    }
  }'

Example Response

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phoneNumber": "+61412345678",
  "unsubscribed": false,
  "properties": {
    "company": "Acme Corp",
    "plan": "premium"
  },
  "segments": [
    { "segmentId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890", "name": "Premium Users" }
  ],
  "topics": [
    { "topicId": "b2c3d4e5-6f78-90ab-cdef-1234567890ab", "name": "Product Updates" }
  ],
  "createdAt": "2026-03-21T10:30:00Z",
  "updatedAt": "2026-03-21T10:30:00Z"
}

List Contacts

GET

/v1/contacts

List all contacts with cursor-based pagination.

Query Parameters

Parameter	Type	Description
`limit`	`number`	Results per page (default: 20, max: 100)
`cursor`	`string`	Cursor for pagination (from previous response)
`search`	`string`	Search by email, first name, or last name

Example Response

{
  "data": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "email": "john.doe@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": "+61412345678",
      "unsubscribed": false,
      "properties": {},
      "segments": [],
      "topics": [],
      "createdAt": "2026-03-21T10:30:00Z",
      "updatedAt": "2026-03-21T10:30:00Z"
    }
  ],
  "cursor": "eyJpZCI6Imxhc3RfaWQifQ==",
  "hasMore": true
}

Get Contact

GET

/v1/contacts/{id}

Retrieve a specific contact by ID.

Path Parameters

Parameter	Type	Description
`id`required	`string`	Contact ID

Update Contact

PATCH

/v1/contacts/{id}

Update a contact. All fields are optional.

Parameters

Parameter	Type	Description
`firstName`	`string`	First name
`lastName`	`string`	Last name
`phoneNumber`	`string`	Phone number in E.164 format. Send empty string to clear.
`unsubscribed`	`boolean`	Unsubscribe status. Unsubscribed contacts are excluded from all broadcasts.
`properties`	`object`	Custom properties (replaces existing)

Example Request

curl -X PATCH https://api.txtly.com.au/v1/contacts/d290f1ee-6c54-4b01-90e6-d701748f0851 \
  -H "Authorization: Bearer tx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "phoneNumber": "+61498765432",
    "properties": {
      "plan": "enterprise"
    }
  }'

Delete Contact

DELETE

/v1/contacts/{id}

Delete a contact.

Path Parameters

Parameter	Type	Description
`id`required	`string`	Contact ID

Example Request

curl -X DELETE https://api.txtly.com.au/v1/contacts/d290f1ee-6c54-4b01-90e6-d701748f0851 \
  -H "Authorization: Bearer tx_your_api_key"

Import Contacts

POST

/v1/contacts/import

Import multiple contacts in bulk. Existing contacts (matched by email) are updated.

Parameters

Parameter	Type	Description
`contacts`required	`object[]`	Array of contact objects with email, firstName, lastName, phoneNumber, unsubscribed
`segmentId`	`string`	Assign all imported contacts to this segment

Example Response

{
  "created": 15,
  "updated": 3,
  "skipped": 0,
  "errors": []
}

Unsubscribes & Suppression

Every contact has a unique unsubscribe token, and every broadcast email automatically includes a one-click unsubscribe link (plus RFC 8058 List-Unsubscribe headers) built from that token — see the Unsubscribe page.

When a contact unsubscribes via that link, two things happen: the contact's unsubscribed flag is set to true (excluding them from broadcasts), and their email address is added to your team's suppression list with reason unsubscribe — which blocks all send paths (transactional emails, batch sends, workflows, and broadcasts) to that address. Suppression entries can be inspected and managed via the /v1/suppressions endpoints.

Contact Properties

Store custom data on contacts using the properties field. Any valid JSON object is supported.

Example Properties

{
  "company": "Acme Corp",
  "plan": "premium",
  "signup_date": "2026-01-15",
  "ltv": 5000,
  "preferences": {
    "newsletter": true,
    "frequency": "weekly"
  }
}