> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contacts Overview

> Understanding contacts and sending lists in Trackly SMS

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

<Steps>
  <Step title="Creation">
    Contacts are created when you:

    * Import a CSV file
    * Add via API
    * Receive an inbound message from a new number
  </Step>

  <Step title="Subscription">
    Contacts subscribe to your sending list(s). They can be subscribed to multiple lists.
  </Step>

  <Step title="Engagement">
    As you send messages, the contact accumulates engagement data: sends, clicks, conversions.
  </Step>

  <Step title="Opt-Out (Optional)">
    If a contact replies STOP, they're automatically unsubscribed and won't receive future messages.
  </Step>
</Steps>

## Contact Data Model

| Field              | Location    | Type     | Description                             |
| ------------------ | ----------- | -------- | --------------------------------------- |
| `phone_number`     | Contact     | String   | E.164 format phone number               |
| `email`            | Contact     | String   | Email address                           |
| `first_name`       | Contact     | String   | First name                              |
| `last_name`        | Contact     | String   | Last name                               |
| `timezone`         | Contact     | String   | Contact timezone                        |
| `carrier`          | Contact     | String   | Phone carrier                           |
| `line_type`        | Contact     | String   | Line type (mobile, voip, etc.)          |
| `is_valid`         | Contact     | Boolean  | Number validation status                |
| `created_at`       | Contact     | DateTime | When first added                        |
| `custom_fields`    | ListContact | Object   | Custom key-value pairs (per-list)       |
| `send_count`       | ListContact | Integer  | Messages sent to this contact           |
| `click_count`      | ListContact | Integer  | Link clicks from this contact           |
| `revenue_total`    | ListContact | Float    | Attributed revenue                      |
| `conversion_count` | ListContact | Integer  | Conversions attributed                  |
| `last_sent_at`     | ListContact | DateTime | Most recent message sent                |
| `last_clicked_at`  | ListContact | DateTime | Most recent click                       |
| `last_revenue_at`  | ListContact | DateTime | Most recent revenue event               |
| `signup_method`    | ListContact | String   | How they subscribed (api, import, etc.) |
| `in_workflow`      | ListContact | Boolean  | Currently 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

### Conversation History

The contact view shows the full two-way message history — every message you sent and every reply the contact sent back, in order. This is the same conversation you can open and reply to from the [Inbox](/guides/inbox/overview); the contact view is the read-oriented, per-contact angle on it.

Inbound replies are also available for targeting — see [reply-based segmentation](/guides/audiences/segmentation-logic) to build audiences from what contacts replied, when, and how often.

## Contact Status

| Status                                                                 | Description                                     | Can Receive Messages |
| ---------------------------------------------------------------------- | ----------------------------------------------- | -------------------- |
| **Active** (`active=True`)                                             | Subscribed and eligible                         | Yes                  |
| **Opted-Out** (`active=False`, `unsub_reason='message'`)               | Replied STOP or opt-out keyword                 | No                   |
| **Bad Response** (`active=False`, `unsub_reason='bad_response'`)       | Carrier rejection or repeated delivery failures | No                   |
| **Invalid Contact** (`active=False`, `unsub_reason='invalid_contact'`) | Number validation failed                        | No                   |
| **Manual** (`active=False`, `unsub_reason='manual'`)                   | Manually unsubscribed by admin or API           | No                   |
| **Complaint** (`active=False`, `unsub_reason='complaint'`)             | Spam complaint received                         | No                   |

## Best Practices

<AccordionGroup>
  <Accordion title="Always use E.164 format">
    Store numbers in E.164 format (+14155551234) for consistency. The platform normalizes imports automatically.
  </Accordion>

  <Accordion title="Use custom fields for segmentation">
    Add custom fields during import or via API to enable granular audience targeting later.
  </Accordion>

  <Accordion title="Monitor opt-out rates">
    High opt-out rates can indicate messaging frequency issues or content problems. Aim for under 2%.
  </Accordion>

  <Accordion title="Clean your lists regularly">
    Remove invalid numbers and long-term non-engagers to improve deliverability and reduce costs.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Importing Contacts" icon="upload" href="/guides/contacts/importing">
    Bulk import via CSV
  </Card>

  <Card title="Custom Fields" icon="tags" href="/guides/contacts/custom-fields">
    Organize with custom fields
  </Card>

  <Card title="Audiences" icon="users" href="/guides/audiences/overview">
    Target contact segments
  </Card>

  <Card title="API" icon="code" href="/api-reference/contacts/list-contacts">
    Manage via API
  </Card>
</CardGroup>