Operator guideENdistribution-listsformupload

Distribution Lists / Form

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

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 form covers

Distribution Lists has no standalone create page. The current FE exposes two form behaviors:

  • a standalone edit page used to rename an existing list
  • an implicit create branch in the upload card when no target list is selected

Rename flow

On /distribution-lists/edit/[id], the operator can:

  • load the current list detail
  • change the Name
  • save the new value with PUT /api/newsletter/distribution-lists/:id
  • reset the local field back to the loaded backend value without sending a request
  • review the current contacts grid rendered under the form
  • see Saving... on the submit button while the rename request is in flight

Implicit create flow

On the Email Newsletters -> Distribution Lists tab:

  • the operator can choose Attach to List (optional) and leave it on Create new list
  • the operator selects a CSV file, can run Check File, and then runs Upload CSV
  • the operator may leave Attach to List empty
  • after a successful file upload, the FE calls POST /api/newsletter/distribution-lists only when no existing list was selected
  • the new list name is derived from the uploaded file name or from a timestamp fallback
  • the FE then parses the CSV locally, extracts deduplicated email-like rows, and continues with the add-contacts step
  • the result dialog exposes counts such as Inserted, Updated, Existing, New, Contact File ID, and Attached Count

Upload helper behavior that matters

  • Check File only calls the preview route and never creates a list or attaches contacts.
  • Upload CSV uploads the file first, then optionally creates a list, then attempts contact attachment.
  • Create new list is a default empty-option branch, not a separate route. The helper names the new list from the file name without extension when possible.
  • Contact attachment is best-effort after upload. A failed create-or-attach step does not roll back the file upload result.
  • The FE clears the selected file after a successful upload, but does not clear the selected target list.

Important caveats

  • The implicit create branch is part of the upload workflow, not a separate route.
  • The current edit page only exposes a single editable field: Name.
  • The form does not expose delete, archive, or remove-contact actions on the verified FE surface.
  • Contact attachment only parses rows that contain an email-like value and only after the upload step succeeds.
  • The list table in the upload card has two navigation paths: the Name button opens the standalone detail page, while the pencil icon opens the rename page.
Calculation notes

Calculations

calculation

Preview versus upload split

Verification
verified_backend_and_core
Logic
`Check File` calls `POST /api/newsletter/files/preview` only., `Upload CSV` calls `POST /api/newsletter/files/upload` first, then optional create-and-attach helper steps., Preview feedback and upload feedback reuse the same `File Result` modal.
calculation

Create list after successful upload

Verification
verified_backend_and_core
Logic
The FE does not create a new list before the file upload request succeeds., When `Attach to List` is left empty, the helper creates a list only after upload success., The helper then uses that returned list id for the add-contacts step.
calculation

Default list-name derivation

Verification
verified_fe_only
Logic
The FE builds the default list name from the uploaded file name without the extension., If the file name is empty after trimming, the helper falls back to `Uploaded YYYY-MM-DD HHMMSS`.
calculation

Local email extraction

Verification
verified_fe_only
Logic
The FE parses the CSV locally after upload success to find a header named `email` or `emailaddress`., Single-column files fall back to column `0`., Only rows containing an `@` are kept, and duplicate email values are removed before attachment.
calculation

Attach errors do not roll back upload

Verification
verified_fe_only
Logic
List-create and add-contacts failures are captured in `attachError` and shown to the operator., The upload result modal still opens with the successful file-upload counters even when the later attach step fails., This is a partial-success flow, not an all-or-nothing transaction.
calculation

Reset name is local only

Verification
verified_fe_only
Logic
`Reset` restores the local input to the last loaded backend `list.name`., The action does not send any API request.
calculation

Successful upload clears file input

Verification
verified_fe_only
Logic
After a successful upload flow, the FE clears the selected file and bumps the hidden file-input key., The selected target list stays unchanged.
Field dictionary

Fields

field

Name

Human-readable list name used in newsletter selection and on standalone detail pages.

Group
editable
Data Type
string
Caveats
The edit surface validates only that the trimmed name is not empty.
field

ID

Internal list identifier shown for reference on the edit page.

Group
read-only
Data Type
integer
field

Contacts

Read-only size indicator shown below the edit controls.

Group
read-only
Data Type
integer
field

Attach to List

Optional target list selector used in the upload card before contacts are attached.

Group
upload-flow
Data Type
select
Caveats
Leaving the selector empty keeps the FE on the `Create new list` branch.
field

Selected CSV

CSV file chosen for preview and upload.

Group
upload-flow
Data Type
file
Caveats
The FE clears this local file state after a successful upload.
field

Name

Clickable list name in the upload-card table that opens the standalone detail page.

Group
upload-grid
Data Type
string
field

Size

Contact-count column shown in the upload-card table.

Group
upload-grid
Data Type
integer
field

Total Rows

Total parsed rows reported by the preview or upload result dialog.

Group
upload-flow
Data Type
integer
field

Inserted

Rows inserted as new contacts during the upload flow.

Group
upload-flow
Data Type
integer
field

Updated

Rows updated during upload when matching contacts already exist.

Group
upload-flow
Data Type
integer
field

Existing

Existing contacts detected by the newsletter service during the upload flow.

Group
upload-flow
Data Type
integer
field

New

New contacts detected by the newsletter service before attachment.

Group
upload-flow
Data Type
integer
field

Contact File ID

Newsletter-service file identifier for the uploaded contact file.

Group
upload-flow
Data Type
integer
field

Attached List

Target list name shown after successful attachment.

Group
upload-flow
Data Type
string
field

Attached Count

Count of contacts actually attached to the selected or newly created list.

Group
upload-flow
Data Type
integer
field

Attach Error

Upload-flow warning shown when list creation, CSV parsing, or contact attachment fails after the file upload step.

Group
upload-flow
Data Type
string
field

Attach Error

Inline upload-card error shown under the helper controls after a best-effort create or attach failure.

Group
upload-flow
Data Type
string
field

Contact Email

Email address shown in the edit-page contacts grid.

Group
edit-grid
Data Type
string
field

First Name

First-name value shown in the edit-page contacts grid.

Group
edit-grid
Data Type
string
field

Last Name

Last-name value shown in the edit-page contacts grid.

Group
edit-grid
Data Type
string
field

Phone

Phone value shown in the edit-page contacts grid.

Group
edit-grid
Data Type
string
field

Tags

Tags rendered as a comma-joined value in the edit-page contacts grid.

Group
edit-grid
Data Type
string[]
Operational notes

Notes

item

The standalone edit route is a rename form, not a full distribution-list editor.

item

Notes 2

The Upload Surface Loads One Paged List Query For The Grid And A Second `Limit
1000` query for the `Attach to List` selector.
item

The create branch is embedded in the upload card and runs only after the file upload succeeds.

item

The FE parses the CSV locally to extract deduplicated email rows before calling `POST /api/distribution-lists/:id/add-contacts`.

item

Upload success does not guarantee list-create or attach success; those later-step failures surface through `attachError` while the file-upload result dialog still opens.

item

The upload card also exposes `Check File`, top and bottom pagination, clickable detail navigation, edit navigation, and a shared result dialog with row-count and attachment feedback.

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 / Detail

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

pageEmail Newsletters / Distribution Lists

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

pageAffiliate Deals / Form

Create and edit form for affiliate deals, including PID, date window, commercial terms, and responsible person.

pageAffiliate Payment Settings / Form

Create and edit form for one affiliate payment-setting record, with visible PID targeting, minimum deposit threshold, and active-state control.

pageAuto Tags Manager / Create

Full rule-builder for a new automatic tagging rule, including tag actions, coupon actions, KPI field selection, and draft impact estimation.