Contacts

Create, retrieve, update, and delete contacts in your workspace.

GET

/contacts

List all contacts with optional filtering and pagination.

Query Parameters

Name	Type	Required	Description
search	string	Optional	Search by email, first name, or last name. Supports multi-word queries.
subscribed	boolean	Optional	Filter by subscription status (true or false).
limit	integer	Optional	Number of contacts to return (default: 100, max: 1000).
offset	integer	Optional	Number of contacts to skip for pagination (default: 0).

curl "https://api.topmail.so/api/v1/contacts?search=jane&subscribed=true&limit=10" \
  -H "Authorization: Bearer tm_live_abc123"

POST

/contacts

Create a new contact.

Request Body

Name	Type	Required	Description
email	string	Required	Email address of the contact.
first_name	string	Optional	First name (max 100 characters).
last_name	string	Optional	Last name (max 100 characters).
attributes	object	Optional	Custom key-value attributes for personalization.
subscribed	boolean	Optional	Subscription status (default: true).
list_id	string (UUID)	Optional	Automatically add the contact to this list.

curl -X POST https://api.topmail.so/api/v1/contacts \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "attributes": {"company": "Acme Inc"},
    "subscribed": true
  }'

GET

/contacts/:id

Retrieve a single contact by ID, including their list memberships.

curl https://api.topmail.so/api/v1/contacts/CONTACT_ID \
  -H "Authorization: Bearer tm_live_abc123"

PATCH

/contacts/:id

Update an existing contact. Only provided fields are modified.

Request Body

Name	Type	Required	Description
email	string	Optional	Updated email address.
first_name	string \| null	Optional	Updated first name. Set to null to clear.
last_name	string \| null	Optional	Updated last name. Set to null to clear.
attributes	object	Optional	Attributes to merge with existing values (does not replace).
subscribed	boolean	Optional	Updated subscription status.

curl -X PATCH https://api.topmail.so/api/v1/contacts/CONTACT_ID \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Janet",
    "attributes": {"plan": "pro"}
  }'

DELETE

/contacts/:id

Permanently delete a contact.

curl -X DELETE https://api.topmail.so/api/v1/contacts/CONTACT_ID \
  -H "Authorization: Bearer tm_live_abc123"