Tags & Lists

Tags and lists are two complementary ways to organize your contacts in SendSeven. Tags are color-coded labels for flexible categorization. Lists are named collections of contacts used for campaigns and bulk operations.

Tags vs. Lists

Aspect	Tags	Lists
Apply to	Contacts and conversations	Contacts only
Use case	Flexible categorization, filtering	Campaign targeting, bulk operations
Visual	Color-coded labels	Named groups
Multiple	A resource can have many tags	A contact can be in many lists

Use tags for dynamic categorization and visual organization. Use lists for campaign recipient groups and structured audience segments.

Required Scopes

Scope	Purpose
contacts:read or conversations:read	List and view tags
tags:create	Create tags
tags:update	Rename or recolor tags
tags:delete	Delete tags
contacts:update	Add/remove tags on contacts
conversations:update	Add/remove tags on conversations
lists:read	List and view contact lists
lists:create	Create new lists
lists:update	Add/remove contacts from lists
lists:delete	Delete lists

---

Tags

List Tags

curl -X GET "https://api.sendseven.com/api/v1/tags?page=1&page_size=20" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json"

{
  "items": [
    {
      "id": "tag_vip",
      "name": "VIP",
      "color": "#EF4444",
      "description": "High-value customers",
      "created_at": "2026-01-10T09:00:00Z"
    },
    {
      "id": "tag_new",
      "name": "New Customer",
      "color": "#10B981",
      "description": "Recently onboarded",
      "created_at": "2026-01-12T14:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 3,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

Usage counts

Add include_usage=true to see how many contacts and conversations carry each tag. Every item then also has contact_count and conversation_count (0 when the tag is unused). The counts cover the tags on the returned page. Leave the parameter off when you don't need the counts; the plain list is faster.

curl -X GET "https://api.sendseven.com/api/v1/tags?include_usage=true&page=1&page_size=20" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00"

{
  "items": [
    {
      "id": "tag_vip",
      "name": "VIP",
      "color": "#EF4444",
      "description": "High-value customers",
      "created_at": "2026-01-10T09:00:00Z",
      "contact_count": 128,
      "conversation_count": 342
    }
  ],
  "pagination": { "page": 1, "page_size": 20, "total": 1, "total_pages": 1, "has_next": false, "has_prev": false }
}

Create a Tag

curl -X POST "https://api.sendseven.com/api/v1/tags" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enterprise",
    "color": "#6366F1",
    "description": "Enterprise-tier customers"
  }'

Field	Type	Required	Description
name	string	Yes	Tag name (max 50 chars, unique per workspace)
color	string	No	Hex color code (e.g., #EF4444)
description	string	No	Tag description (max 255 chars)

Tag names are unique per workspace. The comparison ignores case, accents and trailing spaces, so VIP, vip and vip count as the same name. Creating or renaming a tag to an existing name returns 400:

{"detail": "A tag with the name 'VIP' already exists"}

Tags are also used as team-member skills for routing. See Skill-Based Routing.

Update a Tag

curl -X PUT "https://api.sendseven.com/api/v1/tags/tag_enterprise" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "color": "#8B5CF6",
    "description": "Enterprise and strategic accounts"
  }'

Delete a Tag

Deleting a tag removes it from all contacts and conversations it is applied to.

curl -X DELETE "https://api.sendseven.com/api/v1/tags/tag_enterprise" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00"

Add a Tag to a Contact

curl -X POST "https://api.sendseven.com/api/v1/contacts/contact_xyz789/tags/tag_vip" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json"

Remove a Tag from a Contact

curl -X DELETE "https://api.sendseven.com/api/v1/contacts/contact_xyz789/tags/tag_vip" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00"

Add a Tag to a Conversation

curl -X POST "https://api.sendseven.com/api/v1/conversations/conv_abc123/tags/tag_urgent" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json"

---

Lists

List All Lists

curl -X GET "https://api.sendseven.com/api/v1/lists?page=1" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json"

{
  "items": [
    {
      "id": "list_newsletter",
      "name": "Newsletter Subscribers",
      "description": "Main weekly newsletter recipients",
      "contact_count": 2450,
      "created_at": "2026-01-05T10:00:00Z",
      "updated_at": "2026-02-10T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 5,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

Create a List

curl -X POST "https://api.sendseven.com/api/v1/lists" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Launch Invites",
    "description": "Contacts to invite to the Q2 product launch event"
  }'

Field	Type	Required	Description
name	string	Yes	List name (max 100 chars)
description	string	No	List description (max 255 chars)

Add Contacts to a List

curl -X POST "https://api.sendseven.com/api/v1/lists/list_launch/contacts" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_ids": ["contact_001", "contact_002", "contact_003"]
  }'

{
  "list_id": "list_launch",
  "added": 3,
  "already_in_list": 0,
  "total_contacts": 3
}

Remove a Contact from a List

curl -X DELETE "https://api.sendseven.com/api/v1/lists/list_launch/contacts/contact_003" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00"

Error Responses

Status	Error Code	Description
400	VALIDATION_ERROR	Invalid request body or parameters
401	INVALID_TOKEN	Missing or invalid authentication token
403	INSUFFICIENT_SCOPE	Token lacks required scope
404	RESOURCE_NOT_FOUND	Tag, list, contact, or conversation not found
400	—	A tag with this name already exists
409	DUPLICATE_RESOURCE	List name already exists

Next Steps

• Manage Contacts -- full contact CRUD operations
• Custom Fields -- store custom data on contacts
• Messaging Campaigns -- target lists with campaigns