> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suprsend.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Manual (CSV upload)
> Upload a fixed set of users to a SuprSend List from a CSV in the dashboard — best for one-off campaigns run without engineering involvement.
Upload a CSV of `distinct_id`s to a [List](/docs/lists) from the SuprSend dashboard. The list is a snapshot at upload time — re-upload to update it, or [switch to database sync](/docs/list-sync-via-database) if you want it to refresh automatically.
CSV upload only adds users that already exist in SuprSend — it can't create new user profiles or update user properties and channels. See [Creating user profiles](/docs/users#creating-user-profile-on-suprsend) to identify users first, or use [database sync](/docs/list-sync-via-database) which can create users during the sync.
## Setting up the upload
### 1. Create the list
Go to **Lists → + New List** and fill in:
| Field | Rules |
| ----------- | ------------------------------------------------------------------------------------------------- |
| `list_id` | Required. Unique identifier within the workspace. Use lowercase letters, digits, and underscores. |
| Name | Optional. Display name for the list. |
| Description | Optional. Additional context to help you understand the list's purpose or the users it contains. |
You can edit the name and description later from the **List Settings** button on the list.
### 2. Upload the CSV
Select **Update Users** inside the list details page. Pick how to apply the CSV, upload the file, then click **Update Users**.
| Update type | When to use |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Add** | Appends new users to the existing membership. Use for a rolling list you keep adding to — *e.g. today's signups*. |
| **Replace** | Swaps the current membership for exactly the users in the CSV. Use when the CSV is the full definition of the audience — *e.g. "attendees of the July 2026 webinar"*. |
**CSV format**
| Requirement | Value |
| ----------- | ------------------------------------------------------------------------------------- |
| Column | Exactly one column labeled `distinct_id` (case-sensitive). Extra columns are ignored. |
| Header row | Required — the file's first row must contain `distinct_id`. |
| Delimiter | Comma. |
| Encoding | UTF-8. Save as "CSV UTF-8" from Excel, or export from Google Sheets. |
CSV upload can't update user properties or channels. If you need to sync additional profile data alongside the list, use [database sync](/docs/list-sync-via-database) instead.
## Import logs
Every upload appears on the **Import Logs** tab of the list. Each row shows when the file was uploaded, who uploaded it, the outcome, and a summary of how many users were added.
| Status | Meaning |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **In progress** | The CSV is being read and applied to the list. |
| **Success** | The upload completed. See the count breakdown below. |
| **Failed** | The upload couldn't complete — usually a missing `distinct_id` column, malformed CSV, or file too large. Hover the status or open the log row to see the exact error. |
### Total vs. Added
* **Total** — rows in the CSV, excluding the header row.
* **Added** — users actually added to the list after the upload finished.
`Added` can be lower than `Total` for two reasons:
* **The user is already in the list.** Duplicate `distinct_id`s — either within the CSV or from a previous upload — aren't added again; they count toward `Total` but not `Added`.
* **The user doesn't exist in SuprSend.** CSV upload can't create users, so rows whose `distinct_id` isn't already a user in SuprSend are skipped.
## Troubleshooting
The header row must contain a column named exactly `distinct_id` (lowercase, with no leading or trailing spaces). If your source spreadsheet uses a different header — or the header has stray whitespace around it — rename or trim it before exporting. Also check the `distinct_id` values themselves for leading or trailing spaces, since a padded ID won't match the user in SuprSend.
Either the users are already in the list (safe to ignore) or their `distinct_id`s don't exist in SuprSend. CSV upload can't create users — [create them first](/docs/users#creating-user-profile-on-suprsend), or use [database sync](/docs/list-sync-via-database) which can create users on the fly.
Split the CSV into smaller batches and upload them one after another. Each batch appears as its own row in Import Logs.
Save the CSV as UTF-8. Excel defaults to a locale-specific encoding on export — use **Save As → CSV UTF-8**, or export from Google Sheets which is UTF-8 by default.
## Next steps
Use the uploaded list as the audience for a broadcast.
Trigger a workflow when users enter or exit the list.