Repository navigation
CSV contact import and export #38
Description
There's no way to bulk-import or export contacts, yet apps/docs/content/docs/getting-started/first-broadcast.mdx:8 says "Create or import contacts". Without import, nobody can move off Mailchimp, Beehiiv, Substack, ConvertKit and the like.
Import
- CSV upload with column mapping. Recognize column names from common platform exports automatically: email, first/last name, tags, status, signup date, and custom fields.
- Parse in the browser and send chunks (about 1000 rows) to a bulk endpoint, validating again on the server. Or upload the file and process it in a BullMQ job with progress.
- Statuses can only get stricter: active < unsubscribed < bounced < complained. An import never moves a suppressed or unsubscribed contact back to active, and bounced/complained rows create suppressions. (This ranking comes from https://github.com/marclou/mailcheap
lib/csv-import.js.) - Optionally import historic open and click rates (as
%or 0–1) to seed engagement-ordered sending (Warmup scheduler #5) and dormancy (Dormant contacts segment and re-engagement sequence #29). - Keep imported signup dates, so growth charts don't show an import-day spike.
- Return a report of created, updated and skipped rows, with the reason for each skip.
Export
- Export all contacts, or a segment, to CSV, including tags, custom fields, subscription status and suppression reason.
Add the REST endpoints, MCP tools and docs.
Activity
clbotdev commentedon Oct 19, 2026
Marking this severity: critical. It blocks inviting beehiiv switchers: without import they can't move their list. Specifics from the 19 Oct readiness audit:
beehiiv export format (beehiiv help articles 12258595483543 and 12428610562327)
email,status,tierProposed status mapping
beehiiv-paused(or let the user choose to unsubscribe)beehiiv-pendingtier:<value>Gaps in the current API
subscribed(packages/api-contract/src/schemas/contacts.ts~L26-28: email, name and tags only;subscribedis on update only). Importing an unsubscribed contact would need create + PATCH, with a window where they look subscribed.POST /contacts(packages/api-contract/src/contract.ts:133) and MCPcreate_contact. We need a bulk upsert API (and an MCP tool), with idempotent upsert by email, per-row errors and an async job for large files.apps/docs/content/docs/getting-started/first-broadcast.mdx:8already says "Create or import contacts". The migration guides are tracked in Migration guides: beehiiv, Substack and Mailchimp to SendLit #68.