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)
`first_name`	`string`	First name
`last_name`	`string`	Last name
`unsubscribed`	`boolean`	Whether contact is unsubscribed
`properties`	`object`	Custom JSON properties

Example Request

curl -X POST https://api.txtly.io/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "properties": {
      "company": "Acme Corp",
      "plan": "premium"
    }
  }'

Example Response

{
  "id": "contact_abc123xyz789",
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "unsubscribed": false,
  "properties": {
    "company": "Acme Corp",
    "plan": "premium"
  },
  "created_at": "2026-03-21T10:30:00Z",
  "updated_at": "2026-03-21T10:30:00Z"
}

List Contacts

GET

/v1/contacts

List all contacts with pagination support.

Query Parameters

Parameter	Type	Description
`limit`	`number`	Results per page (default: 20, max: 100)
`offset`	`number`	Number of results to skip

Example Response

{
  "contacts": [
    {
      "id": "contact_abc123xyz789",
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "unsubscribed": false,
      "created_at": "2026-03-21T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 20,
    "offset": 0
  }
}

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
`first_name`	`string`	First name
`last_name`	`string`	Last name
`unsubscribed`	`boolean`	Unsubscribe status
`properties`	`object`	Custom properties (merged with existing)

Example Request

curl -X PATCH https://api.txtly.io/v1/contacts/contact_abc123xyz789 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "properties": {
      "plan": "enterprise"
    }
  }'

Delete Contact

DELETE

/v1/contacts/{id}

Delete a contact. By default, the contact is soft-deleted. Add ?permanent=true to permanently delete.

Path Parameters

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

Query Parameters

Parameter	Type	Description
`permanent`	`boolean`	Permanently delete (default: false for soft delete)

Example Requests

# Soft delete (recoverable)
curl -X DELETE https://api.txtly.io/v1/contacts/contact_abc123xyz789 \
  -H "Authorization: Bearer YOUR_API_KEY"

# Permanent delete (non-recoverable)
curl -X DELETE "https://api.txtly.io/v1/contacts/contact_abc123xyz789?permanent=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

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"
  }
}