Import a reader list (Preview)

Open Contacts → Import in the dashboard. Upload the files from one platform, select its preset, and choose the destination topic. Each file declares how it records reader permission: a supported status column or an explicit export scope. Review that evidence before starting the import.

Prepare the exports

Keep subscribed, unsubscribed, and suppressed readers together in the same import, even when your platform exports them into separate files. When an address occurs more than once, suppression takes precedence over unsubscribe, and unsubscribe takes precedence over subscribed.

• beehiiv: include a suppression-scoped export alongside the subscriber export, or explicitly declare that the subscriber export was filtered to Suppression does not exist. An active status alone does not establish permission to send.
• Mailchimp: declare the scope of each exported file. A filename can suggest a scope in the dashboard, but you confirm it before previewing.
• Substack: include email_disabled. Missing, blank, or unrecognized values are conflicts.
• Kit: include the status column. Unrecognized values are conflicts and never subscribe a reader.

All files, declarations, and request metadata must fit the combined encoded-request limit in the preview reference. The dashboard checks this before submission. If the request is too large, reduce the export cohort while keeping its subscription and suppression evidence together. Preview and start each validate the complete request.

The preview names missing columns and conflicting rows. It changes no contacts. Fix refused files and preview again; there is no default that treats unknown readers as subscribed.

Review and import

Check the destination topic, each file's declared evidence, and the subscribed, unsubscribed, suppressed, and skipped counts. Preview counts reflect the current list; the import checks each reader again as it processes them.

An import preserves existing unsubscribes, suppressions, and bounces in Samva. It records the source, batch, declared evidence, and original signup date when the export supplies one. View that provenance on the contact. New active contacts count toward usage, and normal contact-created automations apply.

Suppression is organization-wide. With a namespace-scoped credential, rows requiring suppression are conflicts and create no contact or subscription. Import those restrictions with an organization credential.

Start the import after reviewing the preview. You can leave the page and return to its saved progress. If processing fails, inspect the job and resume its saved input when it is resumable.

Use the CLI

Give each file as EVIDENCE=PATH. status reads the preset's supported column; an export scope is subscribed, unsubscribed, suppressed, or cleaned/bounced.

samva contacts import --preset mailchimp --topic unsub_7q2xk9mvt4znw8rh \
  --file subscribed=readers.csv --file cleaned/bounced=cleaned.csv --dry-run --json

--dry-run calls the server preview and starts no job. To import the same files, replace it with --idempotency-key migration-1. Save the preview’s planHash and pass it as --plan-hash HASH to submit that reviewed input without previewing again. If the start receipt is lost, retry with the same files, evidence, key, and saved hash. This can recover an admitted job even when the topic was deleted or imports were disabled afterward. The server still checks the input and namespace. Use a new key for a separate import.

samva contacts import-status cimport_7q2xk9mvt4znw8rh --json
samva contacts import-resume cimport_7q2xk9mvt4znw8rh --generation 1 --json

The API exposes the same flow through preview, start or resume, and job progress.