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
contacts:update	Create, update, delete tags; 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
  }
}

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 tenant)
color	string	No	Hex color code (e.g., #EF4444)
description	string	No	Tag description (max 255 chars)

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
409	DUPLICATE_RESOURCE	Tag name or 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