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, custom fields, 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)
  • Custom Fields: Custom key-value pairs for targeting
  • Engagement Data: Click history, conversion data, message counts
  • Subscription Status: Active, opted-out, or invalid

​
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

FieldLocationTypeDescription
phone_numberContactStringE.164 format phone number
emailContactStringEmail address
first_nameContactStringFirst name
last_nameContactStringLast name
timezoneContactStringContact timezone
carrierContactStringPhone carrier
line_typeContactStringLine type (mobile, voip, etc.)
is_validContactBooleanNumber validation status
created_atContactDateTimeWhen first added
custom_fieldsListContactObjectCustom key-value pairs (per-list)
send_countListContactIntegerMessages sent to this contact
click_countListContactIntegerLink clicks from this contact
revenue_totalListContactFloatAttributed revenue
conversion_countListContactIntegerConversions attributed
last_sent_atListContactDateTimeMost recent message sent
last_clicked_atListContactDateTimeMost recent click
last_revenue_atListContactDateTimeMost recent revenue event
signup_methodListContactStringHow they subscribed (api, import, etc.)
in_workflowListContactBooleanCurrently in an active journey

​
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 custom fields and values
  • Subscription status per list
  • Message history
  • Click and conversion events

​
Contact Status

StatusDescriptionCan Receive Messages
Active (active=True)Subscribed and eligibleYes
Opted-Out (active=False, unsub_reason='message')Replied STOP or opt-out keywordNo
Bad Response (active=False, unsub_reason='bad_response')Carrier rejection or repeated delivery failuresNo
Invalid Contact (active=False, unsub_reason='invalid_contact')Number validation failedNo
Manual (active=False, unsub_reason='manual')Manually unsubscribed by admin or APINo
Complaint (active=False, unsub_reason='complaint')Spam complaint receivedNo

​
Best Practices

Store numbers in E.164 format (+14155551234) for consistency. The platform normalizes imports automatically.
Add custom fields during import or via API to enable granular 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

Custom Fields

Organize with custom fields

Audiences

Target contact segments

API

Manage via API