Operator guideENdistribution-listsuploadcsv

Distribution Lists / Upload Flow

CSV preview and upload flow used to validate files, create a target list when needed, and attach contacts.

Reader view

Clean portal guidance

This page keeps the operator explanation, field and action descriptions, and screenshots visible without exposing repo paths, raw sidecars, or editorial-only implementation details.

Narrative content

Page body

What this flow does

The upload card on Email Newsletters -> Distribution Lists is the real operational entrypoint for creating or extending recipient lists.

The flow is:

  1. choose an optional target list
  2. select a CSV file
  3. preview the file
  4. upload the file
  5. create a list automatically when no target list is selected
  6. parse emails from the CSV in the FE
  7. attach the parsed emails to the chosen or newly created list
  8. show the final result modal

Important caveats

  • The target-list selector uses an empty value labelled Create new list. That is not a placeholder-only state; it is the actual create branch.
  • Check File and Upload CSV are different steps. Preview validates the file first; upload performs the persistent flow.
  • Preview does not clear the selected file. The FE keeps the file in local state until a successful upload resets the input.
  • The FE looks for an email or emailAddress column. If the file has only one column, that single column is treated as the email column.
  • Upload CSV can run even when Check File was never used.
  • The create-list branch happens only after a successful file upload.
  • The default new-list name comes from the uploaded file name, with a timestamp fallback only when the file base name is empty.
  • Attach errors can appear even when the file upload itself succeeded.
  • The final dialog title is File Result and is reused for both preview and upload outcomes.
Calculation notes

Calculations

calculation

Email column detection

Attachment depends on the FE being able to extract email-like values from the CSV.

Inputs
selected_csv
Transform
The FE normalizes CSV headers, looks for `email` or `emailAddress`, and falls back to the only column when the file has a single column.
calculation

Default list name generation

The auto-created list name is usually predictable from the uploaded file name.

Inputs
selected_csv
Transform
When no target list is selected and upload succeeds, the FE derives the new list name from the file base name, with a timestamp fallback only when the base name is empty.
calculation

Create-list branch after upload

`Create new list` is not an immediate form save; it is a branch inside the upload sequence.

Inputs
attach_to_list, selected_csv
Transform
The FE creates a distribution list only after `POST /api/newsletter/files/upload` succeeds and only when no existing target list was selected.
calculation

Independent attach failure

A successful upload does not guarantee that contacts were attached.

Inputs
attach_error
Transform
After file upload succeeds, CSV parsing or `add-contacts` can still fail separately, and the final result modal reports that through `Attach Error`.
calculation

File reset after successful upload

Operators can preview repeatedly, but a completed upload clears the current file selection.

Inputs
selected_csv
Transform
Preview leaves the chosen file in local state, but successful upload resets the input and bumps the input key so a new file must be selected for another run.
Field dictionary

Fields

field

Attach to List (optional)

Optional target list chooser used before upload starts.

Visual Type
select
Caveats
The empty option is rendered as `Create new list`.
field

Selected CSV

CSV chosen for preview and upload.

Visual Type
file
Caveats
Preview keeps the selected file in place., Successful upload resets the file input.
field

Success

Top-level success indicator shown inside the `File Result` dialog as `YES` or `NO`.

Visual Type
result-stat
field

Total Rows

Number of parsed rows shown in the result dialog.

Visual Type
result-stat
field

Inserted

Number of newly inserted contact rows reported by the newsletter service.

Visual Type
result-stat
field

Updated

Number of existing contacts updated during file processing.

Visual Type
result-stat
field

Existing

Number of contacts already known before this run.

Visual Type
result-stat
field

New

Number of contacts newly discovered in the file.

Visual Type
result-stat
field

Contact File ID

Internal file-processing identifier returned by the newsletter service.

Visual Type
result-stat
field

Attached List

Final target list name used for the attach step.

Visual Type
result-stat
field

Attached Count

Number of emails the FE reports as attached to the chosen list.

Visual Type
result-stat
field

Attach Error

Follow-up failure shown when file upload succeeded but contact attachment failed later in the chain.

Visual Type
error-text
field

File Result

Shared modal reused for both preview and upload outcomes.

Visual Type
modal
Operational notes

Notes

item

The FE parses CSV emails locally before it calls `add-contacts`.

item

`Check File` and `Upload CSV` use direct `axios` requests inside `DistributionListView`.

item

Successful upload calls `mutate()` on the distribution-list list hook and resets the local file input.

item

The attach step can fail independently from file upload, so operators should read the result dialog carefully.

Related references

Related pages

pageDistribution Lists

Operator documentation for newsletter recipient lists, including detail, rename, contacts inspection, and CSV upload or attach flows.

pageDistribution Lists / Contacts

Read-only contact grid attached to one newsletter distribution list.

pageDistribution Lists / Detail

Read-only detail workspace for one distribution list and the contacts currently attached to it.

pageDistribution Lists / Form

Rename flow for an existing distribution list plus the implicit create-a-list branch triggered from the CSV upload card.

pageEmail Newsletters

Operator workspace for newsletter campaigns, distribution lists, and send-log review through the backoffice newsletter proxy.

pageEmail Newsletters / Distribution Lists

Reusable contact-list inventory with CSV preview, upload, create, and add-contacts actions.