govoplan-campaign/docs/RECIPIENT_IMPORT_GUIDE.md

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.