Skip to main content
Labels are custom key-value pairs attached to contacts. Use them to organize contacts, track metadata, and build targeted audiences.

​
What Are Labels?

Labels are flexible metadata you define. Each label has:
  • Key: The label name (e.g., source, tier, cohort)
  • Value: The label value (e.g., facebook, gold, january2024)
Contact: +14155551234
Labels:
  source: facebook
  campaign: summer_promo
  tier: gold
  cohort: 2024-01

​
Common Label Patterns

​
Acquisition Source

Track where contacts came from:
KeyExample Values
sourcefacebook, google, organic, referral
campaignsummer2024, black_friday, launch
landing_page/promo, /signup, /offer
ad_setlookalike_1, interest_targeting

​
Contact Segmentation

Categorize contacts by behavior or value:
KeyExample Values
tiergold, silver, bronze
engagementhigh, medium, low
buyer_statuspurchased, browsed, new
ltv_bucket0-50, 50-200, 200+

​
Temporal Data

Track time-based information:
KeyExample Values
cohort2024-01, 2024-Q1, week_12
signup_date2024-01-15
last_purchase2024-03-20

​
Custom Attributes

Store any relevant metadata:
KeyExample Values
stateCA, NY, TX
languageen, es, fr
interestfitness, tech, fashion
age_range18-24, 25-34, 35-44

​
Adding Labels

​
During Import

Include label_ prefixed columns in your CSV: 
phone_number,label_source,label_campaign,label_tier
+14155551234,facebook,summer2024,gold

​
Via API

Include labels when creating contacts: 
curl -X POST https://app.tracklysms.com/api/v1/contacts \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "labels": {
      "source": "api",
      "campaign": "onboarding"
    }
  }'

​
In Dashboard

  1. Go to Sending Lists > select list > Contacts
  2. Click on a contact
  3. Click Edit Labels
  4. Add or modify labels
  5. Click Save

​
Using Labels in Audiences

Labels are the primary way to segment contacts into audiences. Use them in audience conditions:

​
Basic Condition

label:source = facebook
Matches contacts with source label equal to facebook.

​
Multiple Values

label:tier IN [gold, silver]
Matches contacts with tier label of either gold or silver.

​
Existence Check

label:vip EXISTS
Matches contacts that have any value for the vip label.

​
Negation

label:churned NOT EXISTS
Matches contacts that don’t have the churned label.

​
Label Best Practices

Establish naming conventions and stick to them:
  • Use lowercase: source not Source
  • Use underscores: sign_up_date not sign-up-date
  • Be specific: acquisition_source not just src
Use consistent values across imports:
  • facebook not sometimes Facebook or FB
  • 2024-01-15 not Jan 15, 2024 or 1/15/24
Add labels you’ll actually use for targeting. Too many labels create noise.
Maintain a reference of what labels you use and what values are valid. Share with your team.
Labels like churned, complained, high_risk help you exclude contacts from sends.

​
Bulk Label Updates

​
Add Label to Audience

To add a label to all contacts in an audience:
  1. Go to Audiences
  2. Select the audience
  3. Click Actions > Add Label
  4. Enter key and value
  5. Confirm
This adds the label to all contacts currently matching the audience. It’s a one-time operation, not dynamic.

​
Remove Label from Audience

  1. Go to Audiences
  2. Select the audience
  3. Click Actions > Remove Label
  4. Enter the key to remove
  5. Confirm

​
Label Limits

LimitValue
Labels per contact50
Key length64 characters
Value length256 characters
Characters allowedAlphanumeric, underscores, hyphens

​
Viewing Label Usage

To see all labels in use across your contacts:
  1. Go to Audiences > New Audience
  2. Click Add Condition > Label
  3. The dropdown shows all existing label keys
  4. Select a key to see its values
This helps you understand what labels exist in your data.

​
Example: Full Segmentation Strategy

Here’s an example label strategy for an e-commerce brand: 
Acquisition:
  source: facebook | google | organic | email | referral
  campaign: (campaign name)
  cohort: 2024-Q1 | 2024-Q2 | ...

Behavior:
  buyer_status: never | once | repeat
  last_purchase_days: 7 | 30 | 90 | 180
  engagement_level: high | medium | low

Value:
  ltv_tier: vip | standard | new
  aov_bucket: low | medium | high

Preferences:
  category_interest: electronics | fashion | home
  promo_responsive: true | false
This enables audiences like:
  • VIP Winback: ltv_tier=vip AND last_purchase_days=90
  • New High Engagers: cohort=2024-Q1 AND engagement_level=high AND buyer_status=never
  • Promo Candidates: promo_responsive=true AND buyer_status=once

​
Next Steps

Building Audiences

Use labels for targeting

Segmentation Logic

Combine label conditions

Import Contacts

Add labels during import