Tags

Tag contacts for organization, filtering, and automation triggers.

GET

/tags

List all tags with contact counts.

Query Parameters

Name	Type	Required	Description
search	string	Optional	Search tags by name.
limit	integer	Optional	Number of tags to return (default: 100, max: 1000).
offset	integer	Optional	Number of tags to skip for pagination (default: 0).

curl "https://api.topmail.so/api/v1/tags?search=vip&limit=20" \
  -H "Authorization: Bearer tm_live_abc123"

GET

/tags/:id

Retrieve a single tag by ID.

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

POST

/tags

Create a new tag.

Request Body

Name	Type	Required	Description
name	string	Required	Tag name (max 50 characters).
color	string	Optional	Hex color code (default: #6366f1).
description	string	Optional	Tag description (max 200 characters).

curl -X POST https://api.topmail.so/api/v1/tags \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Beta Tester",
    "color": "#10b981",
    "description": "Users in the beta program"
  }'

Color Format

Colors must be valid hex codes (e.g. #6366f1). If omitted, the default indigo color #6366f1 is used.

PATCH

/tags/:id

Update a tag. Only provided fields are modified.

Request Body

Name	Type	Required	Description
name	string	Optional	Updated tag name.
color	string	Optional	Updated hex color code.
description	string \| null	Optional	Updated description. Set to null to clear.

curl -X PATCH https://api.topmail.so/api/v1/tags/TAG_ID \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"name": "Early Adopter", "color": "#f59e0b"}'

DELETE

/tags/:id

Permanently delete a tag. All tag assignments are removed from contacts.

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

Tag Assignments

Manage which contacts are assigned to a tag.

GET

/tags/:id/contacts

List contacts assigned to a tag.

Query Parameters

Name	Type	Required	Description
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/tags/TAG_ID/contacts?limit=50" \
  -H "Authorization: Bearer tm_live_abc123"

POST

/tags/:id/contacts

Assign a tag to one or more contacts.

Request Body

Name	Type	Required	Description
contact_ids	string[]	Required	Array of contact UUIDs to tag (min: 1, max: 500).

curl -X POST https://api.topmail.so/api/v1/tags/TAG_ID/contacts \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_ids": [
      "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "c2b3c4d5-e6f7-8901-bcde-f12345678901"
    ]
  }'

DELETE

/tags/:id/contacts

Remove a tag from one or more contacts.

Request Body

Name	Type	Required	Description
contact_ids	string[]	Required	Array of contact UUIDs to untag (min: 1, max: 500).

curl -X DELETE https://api.topmail.so/api/v1/tags/TAG_ID/contacts \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_ids": ["c1a2b3c4-d5e6-7890-abcd-ef1234567890"]
  }'