# Recipient Import Guide

Recipient import lets campaign authors turn spreadsheet-like source data into
campaign-local recipient entries. It is intentionally campaign-local:
reusable address books and Adrema-style address management belong in the
`govoplan-addresses` module.

## Supported Inputs

The current importer is designed for tabular data with a header row. CSV and
spreadsheet-derived tables should be normalized before import so the campaign UI
sees:

- column headers
- row values
- source filename and sheet name when available
- a stable ordered and unordered header fingerprint

Avoid importing production secrets or credentials as recipient fields. Recipient
custom fields may be used in templates and reports, so they should be treated as
campaign data.

## Mapping Fields

Common headers are detected automatically:

- `email`, `e_mail`, `mail`, `to`, `to_email`, `recipient`,
  `recipient_email`
- `name`, `full_name`, `recipient_name`, `to_name`
- `id`, `entry_id`, `recipient_id`

Authors can map columns to address fields:

- `from`
- `to`
- `cc`
- `bcc`
- `reply_to`

Rows without a valid `to` address should remain visible with validation issues
instead of disappearing silently. Authors should be able to fix the source file,
adjust the mapping, or exclude the row before building the campaign.

## Mapping Profiles

Mapping profiles save a known column layout so repeated imports can reuse the
same mapping. The importer stores ordered and unordered header fingerprints so a
profile can distinguish exact column order from equivalent column sets.

Administrators should curate shared profiles only for stable recurring sources.
Campaign-local profiles are acceptable for one-off work and experiments.

## User Workflow

1. Open the campaign recipient/data import screen.
2. Upload or paste a tabular source.
3. Review detected headers and preview rows.
4. Pick or adjust a mapping profile.
5. Confirm validation issues, exclusions, and generated recipient ids.
6. Import into the campaign draft.
7. Build messages and review recipient-specific evidence before sending.

## Admin Workflow

Administrators should:

- define naming conventions for recurring mapping profiles
- verify that imported fields have a lawful processing basis for the campaign
- keep reusable address-directory ownership out of campaigns because
  `govoplan-addresses` owns that domain
- use campaign reports and audit evidence to trace which source produced which
  recipient entries
- remove obsolete shared profiles when an upstream source layout changes

## Evidence Expectations

The campaign should preserve enough evidence to explain a send:

- source filename and sheet name where available
- header fingerprints
- mapping profile id/name when used
- row number or source id
- validation status and exclusion reason
- final recipient addresses used for the built message

The evidence should be available in reports without requiring the original
source file to be reprocessed.