Migrate from beehiiv to Unitpost

Before you start

• A beehiiv API key: Settings → Workspace Settings → API → Create New API Key. Only an Owner or Admin can create one, and beehiiv asks you to finish Stripe Identity Verification first.
• A beehiiv key sees every publication in the workspace unless it was limited to some, which paid plans allow. Only the publications it sees import.
• beehiiv keys carry every permission; there is no read-only key. The importer only reads; delete the key when the move is done.
• beehiiv's Free plan allows 30 API requests a minute, so a large list imports slowly. Leave the job running.
• A Unitpost API key for your app with emails:send, plus contacts:write and topics:write if your signup form adds contacts and opts them into a publication's topic, created in API keys.
• A second Unitpost key for the migration steps, with suppressions:write, templates:write and webhooks:manage, saved as UNITPOST_MIGRATION_KEY. Keep it out of your app and revoke it once the move is done.
• Access to your DNS host.

The cut-over plan

beehiiv keeps sending until the last step, so there is no gap in delivery.

1. 1

   Copy beehiiv's suppression list

   beehiiv keeps hard bounces, repeated delivery failures, spam complaints and manual blocks on a Suppression list (Subscribers → Suppression list). Its API can't read the list and its help page describes no export, so copy the addresses into a file, one per line. Paste them into Suppressions or add them with POST /api/v1/suppressions before you import; that also makes those contacts arrive unsubscribed.

   copy-suppressions.mjs

   import { readFileSync } from "node:fs";
   import { Unitpost } from "unitpost";
   
   const unitpost = new Unitpost(process.env.UNITPOST_MIGRATION_KEY);
   
   // One address per line, copied from beehiiv's Suppression list.
   const emails = readFileSync("beehiiv-suppressed.txt", "utf8")
     .split(/\r?\n/)
     .map((line) => line.trim().toLowerCase())
     .filter(Boolean);
   
   // Up to 1,000 per call. reason "import" makes the contact import mark them unsubscribed.
   for (let i = 0; i < emails.length; i += 1000) {
     const { error } = await unitpost.suppressions.create({
       emails: emails.slice(i, i + 1000),
       reason: "import",
     });
     if (error) throw new Error(error.message);
   }

2. 2

   Run the Migration Assistant

   Paste the key in Settings → Migration. The preview lists your publications, the subscribers it leaves out, paused and paid subscribers, your automations, and whether tags came back.

3. 3

   Bring tags by CSV if they didn't come back

   If the preview says tags didn't come over, export subscribers as CSV from beehiiv, import the tags column in Contacts as a custom field, and build a dynamic segment per tag with a contains condition on that field.

4. 4

   Verify your domain

   Open Domains and publish the records shown: MX and SPF on unitpost.<your domain> and a DKIM TXT under _domainkey. They don't replace beehiiv's records, so both stay authenticated while you move. Keep your single _dmarc record.

5. 5

   Rewrite merge tags and publish

   {{First Name | Reader}} is now {{first_name}} with the fallback dropped, and {{email}}, {{unsubscribe_url}} and your custom fields map by name. beehiiv-only tags such as {{rp_refer_url}}, {{publication_name}} and {{subscriber_id}} stay as written for you to replace. Posts arrive as beehiiv's rendered HTML; publish each template you keep with PATCH /api/v1/email/templates/{id}.

6. 6

   Point signups at Unitpost

   Your beehiiv website and forms keep adding readers to beehiiv. Send signups from your own form with POST /api/v1/contacts. beehiiv's custom_fields list of { name, value } becomes a custom_fields object, and newsletter_list_ids becomes a topic subscription on the contact.

   signup.ts

   // Before: beehiiv
   await fetch("https://api.beehiiv.com/v2/publications/" + PUBLICATION_ID + "/subscriptions", {
     method: "POST",
     headers: { Authorization: "Bearer " + process.env.BEEHIIV_API_KEY, "content-type": "application/json" },
     body: JSON.stringify({
       email: "user@example.com",
       custom_fields: [{ name: "First Name", value: "Ada" }],
       newsletter_list_ids: [LIST_ID],
     }),
   });
   
   // After: Unitpost
   import { Unitpost } from "unitpost";
   const unitpost = new Unitpost(process.env.UNITPOST_API_KEY);
   const { error } = await unitpost.contacts.create({ email: "user@example.com", first_name: "Ada" });
   // 409 conflict: the contact already exists, which is fine for a signup.
   if (error && error.code !== "conflict") throw new Error(error.message);
   // A newsletter list became a topic: record that the reader chose it.
   await unitpost.email.topics.setTopic("user@example.com", { topic_id: "top_123", subscribed: true });

7. 7

   Re-key and enable webhooks

   beehiiv delivers webhooks through Svix, and Unitpost uses the same svix-id, svix-timestamp and svix-signature headers, so your handler needs the new whsec_ secret and the new event names. Rotate the secret in Webhooks to see it, then set status to enabled.

8. 8

   Test, move traffic, then delete the key

   Send each template with POST /api/v1/email/templates/{id}/test-send and fire POST /api/v1/webhooks/{id}/test at each endpoint. Send your next post from Unitpost as a campaign to a small segment first, then to the topic. Delete the beehiiv key, and keep beehiiv only for what you still use there.

Before you cancel beehiiv

• Copy the Suppression list once more and add any new addresses here.
• Export subscribers as CSV, including the unconfirmed ones the importer leaves out.
• Move paid subscriptions to your payment tool, or keep beehiiv for them.
• Keep or redirect your beehiiv website and its archive; Unitpost doesn't host one.
• Delete beehiiv's DNS records once no mail goes through beehiiv. Keep _dmarc and Unitpost's records.
• Delete the beehiiv API key you used for the import.

Facts about beehiiv checked 2026-11-05. Providers change their APIs and plans; check their docs before you rely on a detail.