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

# Contacts and lists

> Manage recipients and their subscription state

A **contact** represents a person you might message — typically built from an email address, with an optional phone number for SMS. A **list** is a named group of contacts, useful for sending the same campaign to many people or for organizing audiences (e.g. "Newsletter subscribers", "Beta testers").

## Contacts are optional for transactional sending

[Send a message](/api-reference/messages/send) never requires a `contact_id` — you can pass `to` directly for one-off transactional messages like password resets or receipts. Create contacts when you want Pulsewave to track subscription state and unsubscribes on your behalf, which matters most for marketing or digest-style sends to a list.

## Subscription state

Every contact has a `subscribed` boolean. It starts `true` and flips to `false` when:

* The contact clicks an unsubscribe link in a message
* The contact marks a message as spam (a [`message.complained`](/api-reference/webhook-events/message-complained) event also fires)
* You explicitly [update](/api-reference/contacts/update) the contact

Pulsewave automatically skips sending to unsubscribed contacts when you target a list, and fires a [`contact.unsubscribed`](/api-reference/webhook-events/contact-unsubscribed) event so you can mirror the state in your own database.

<Note>
  Unsubscribes are channel-wide. There's no separate opt-out for email vs. SMS on the same contact — if you need independent consent per channel, model that with `metadata` and check it in your own application before sending.
</Note>

## Working with lists

```bash theme={null}
# Create a list
curl -X POST https://api.pulsewave.dev/v1/lists \
  -H "Authorization: Bearer pw_live_..." \
  -d '{ "name": "Newsletter subscribers" }'

# Add a contact to it
curl -X POST https://api.pulsewave.dev/v1/lists/lst_7q1m4z/contacts \
  -H "Authorization: Bearer pw_live_..." \
  -d '{ "contact_id": "ct_5n2p9x" }'
```

A contact can belong to any number of lists. Deleting a list removes the grouping but does not delete the contacts in it; deleting a contact removes it from every list it belonged to.