Skip to main content
Contacts are the foundation of your SMS marketing. Every phone number you message is stored as a contact, with subscription status, labels, and engagement history.

​
Key Concepts

​
Contact

A contact represents a phone number in the system. Each contact stores:
  • Phone Number: In E.164 format (+14155551234)
  • Labels: Custom key-value pairs for targeting
  • Engagement Data: Click history, conversion data, message counts
  • Subscription Status: Active, opted-out, or suppressed

​
Sending List

A sending list is a phone number you send messages from. Contacts subscribe to sending lists. 
Sending List: +18005551234 (your number)
├── Contact: +14155551234 (subscribed)
├── Contact: +14155551235 (subscribed)
└── Contact: +14155551236 (opted-out)

​
ListContact

The relationship between a contact and a sending list. This tracks:
  • When the contact subscribed
  • How they subscribed (API, import, journey)
  • Current subscription status
  • Opt-out timestamp (if applicable)

​
Contact Lifecycle

1

Creation

Contacts are created when you:
  • Import a CSV file
  • Add via API
  • Receive an inbound message from a new number
2

Subscription

Contacts subscribe to your sending list(s). They can be subscribed to multiple lists.
3

Engagement

As you send messages, the contact accumulates engagement data: sends, clicks, conversions.
4

Opt-Out (Optional)

If a contact replies STOP, they’re automatically unsubscribed and won’t receive future messages.

​
Contact Data Model

FieldTypeDescription
phone_numberStringE.164 format phone number
labelsObjectCustom key-value pairs
created_atDateTimeWhen first added
total_sendsIntegerMessages sent to this contact
total_clicksIntegerLink clicks from this contact
total_revenueFloatAttributed revenue
last_sentDateTimeMost recent message sent
last_clickedDateTimeMost recent click

​
Working with Contacts

​
View Contacts

  1. Go to Sending Lists
  2. Click on a list
  3. View the Contacts tab
You’ll see all contacts subscribed to that list with their status and engagement metrics.

​
Contact Details

Click on any contact to see:
  • Full engagement history
  • All labels and values
  • Subscription status per list
  • Message history
  • Click and conversion events

​
Contact Status

StatusDescriptionCan Receive Messages
ActiveSubscribed and eligibleYes
Opted-OutReplied STOPNo
SuppressedManually suppressedNo
InvalidNumber format issuesNo

​
Best Practices

Store numbers in E.164 format (+14155551234) for consistency. The platform normalizes imports automatically.
Add labels during import or via API to enable powerful audience targeting later.
High opt-out rates can indicate messaging frequency issues or content problems. Aim for under 2%.
Remove invalid numbers and long-term non-engagers to improve deliverability and reduce costs.

​
Next Steps

Importing Contacts

Bulk import via CSV

Labels

Organize with labels

Audiences

Target contact segments

API

Manage via API