Email Contact Imports: Validate a Small Sample Before Accepting the File

TL;DR

• Treat large contact imports as data changes and verify them by validating a small representative fixture that includes expected formats and edge cases before accepting the full file.
• Use explicit column contracts, explicit mapping and a dry‑run preview that reports counts and representative examples so operators can catch semantic mistakes and decide actions before committing.
• Check eligibility and preference evidence during preview and keep an auditable record after import so previewed changes and source context validate success and allow investigation.

Treat import as a data change, not a file upload

A contact file can change identities, audience membership and communication preferences. Parsing it successfully is only the first step. Before accepting a large file, establish what the import is allowed to create or update and how the result will be reviewed.

Start with a small representative fixture rather than the easiest first few rows. Include the formats and edge cases that the full file is expected to contain. The purpose is to verify the mapping and policy before mistakes are multiplied across the audience.

Do not use the import itself as evidence that the contacts are eligible for a campaign.

Define the column contract

List required columns, optional columns and the meaning of each field. An external contact ID, email address and subscription status are different facts; the importer should not infer their meaning solely from a vaguely similar header.

For an illustrative CRM export, “active” might mean an active customer account rather than consent to receive product updates. Mapping that column directly to a marketing subscription would change its meaning.

Require an explicit mapping and show examples of the resulting records. This gives the operator a chance to catch semantic mistakes that a CSV parser cannot detect.

Parse the actual file format

Use a proper parser for the supported format. RFC 4180 describes common CSV conventions, including quoted fields that can contain commas and line breaks. Splitting every line on commas is not a reliable substitute.

Include a name containing a comma, a quoted value and a multiline field in the test fixture. Check the encoding and preserve non-Latin names correctly. If the product supports only a defined format, report unsupported input clearly rather than silently corrupting it.

Keep structural parsing errors separate from business validation errors so the operator knows what must be corrected.

Test identity and duplicate handling

Decide how the importer identifies an existing contact and what happens when several rows refer to the same destination or external ID. Avoid silently combining people because their names look similar.

For the CRM example, two different customer records may share a team mailbox. The correct handling depends on the application's contact model, not a generic rule that every matching address means the same person.

Show duplicate candidates and the chosen action in the preview. A merge, update and new record have different consequences, so the result should be visible before the full import is committed.

Preserve preference evidence

A subscription field needs a defined scope and trustworthy source. Unknown values should remain unknown or follow an explicitly reviewed policy; they should not default to opt-in merely because the file omitted a column.

Also protect newer recipient choices from stale exports. A contact who unsubscribed yesterday should not be silently resubscribed by a file generated last week. Retain the source timestamp and apply the documented conflict rule.

The SendDart consent-record guide is useful background for recording these decisions. An import preview should make preference changes especially clear because they affect future communication eligibility.

Separate validation from delivery guarantees

An address passing syntax validation is not proof that the mailbox exists, that a message will be accepted or that the person wants the campaign. Treat these as separate questions.

Use the email-verification evaluation guide when deciding whether an additional verification service fits the workflow. Do not erase an opt-out or substitute a verification result for consent evidence.

Likewise, a previously deliverable address can later fail. Import validation improves data handling; it does not remove the need to process later delivery outcomes appropriately.

Produce a dry-run summary with useful counts

Before committing, show how many rows would create contacts, update fields, remain unchanged, be skipped or require investigation. Include representative sanitized examples and specific reasons for errors.

For a hypothetical 20-row fixture, the useful output is not merely “18 valid.” The operator needs to know whether the other two are malformed, ambiguous duplicates or blocked preference changes, and whether the 18 would overwrite existing information.

Keep the preview tied to the exact file and mapping configuration. If either changes, invalidate the approval or rerun the review rather than applying an old decision to different data.

Make the import result auditable

After the authorized import, retain an import identifier, source context, mapping version and summary of actions. Provide a controlled way to inspect errors without distributing unnecessary personal data.

If correction is needed, use the recorded changes to plan it. Do not assume that deleting newly created rows will reverse updates or merges applied to existing contacts.

SendDart audience operations should receive data that has already passed the application's identity, preference and mapping decisions. A careful sample review makes the full import more predictable and gives the team a concrete explanation of what changed and why.