# Lists

The Lists service lets tenant administrators create named contact lists, populate them via CSV upload or individual user selection, and use them as a targeting dimension in the Campaigns and Audiences APIs.

## Use Cases

- Upload a CSV of leads or newsletter subscribers and target them in a campaign
- Select existing platform users and group them into a list for re-engagement
- Cross-reference a list against Postal email sends to measure open and click rates per list

## Member Sources

- **CSV import**: Upload a file with an `email` column via a public URL. Members without an existing user account are stored as email-only entries.
- **User selection**: Add members by `user_id` — their email is resolved from the users table automatically.
- **Direct email**: Add raw email addresses. If `first_name` and `last_name` are provided and the user does not exist, a user is created with the specified type (default: `newsletter`).

## Member Types

Each member carries a `type` that reflects how they were added:

- `newsletter` — opted in via a subscription form
- `contact` — imported lead with no platform account
- `customer` — existing platform buyer
- Any custom type string is accepted

## Analytics

The `GET /v1/lists/:list_id/analytics` endpoint cross-references list member emails against Postal email send records for a given `email_type`, returning per-list open rate, click rate, and delivery rate.