Migrate from Loops to Unitpost

Before you start

• A full audience CSV from Loops: in Audience, open the ••• menu in the filter box and choose Download.
• Any Loops API key (Settings → API); the importer only reads mailing lists, and step 2 uses it for suppression checks.
• A Unitpost API key with emails:send for your app, created in API keys.
• A second Unitpost key for the migration steps, with contacts:write, suppressions:write, topics: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

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

1. 1

   Convert the consent column

   Loops' CSV has a subscribed column, true for contacts who get campaigns. Add a column named unsubscribed that is true where subscribed is false, and delete subscribed. Mapping subscribed onto Unitpost's opt-out field would flip everyone's consent, and leaving it unmapped imports unsubscribed contacts as subscribed.

2. 2

   Copy suppressed addresses

   Loops has no list of suppressed contacts. Check each exported address with Loops' GET /api/v1/contacts/suppression?email= and add the suppressed ones with POST /api/v1/suppressions. Doing this before the contact import also makes those contacts arrive unsubscribed.

   copy-suppressions.mjs

   import { Unitpost } from "unitpost";
   
   const unitpost = new Unitpost(process.env.UNITPOST_MIGRATION_KEY);
   const emails = readEmailColumn("loops-audience.csv"); // your CSV parser
   
   // Loops answers one address at a time and rate-limits its API. A failed check
   // stops the copy: a list with gaps would let you re-mail a bounce or complaint.
   const suppressed = [];
   for (const email of emails) {
     const url = "https://app.loops.so/api/v1/contacts/suppression?email=" + encodeURIComponent(email);
     for (let attempt = 1; ; attempt++) {
       const res = await fetch(url, { headers: { Authorization: "Bearer " + process.env.LOOPS_API_KEY } });
       if (res.ok) {
         if ((await res.json()).isSuppressed) suppressed.push(email);
         break;
       }
       if ((res.status === 429 || res.status >= 500) && attempt < 5) {
         const wait = Number(res.headers.get("retry-after")) || 2 ** attempt;
         await new Promise((r) => setTimeout(r, wait * 1000));
         continue;
       }
       throw new Error(`Suppression check failed for ${email}: HTTP ${res.status}. Fix it and rerun.`);
     }
   }
   
   // Up to 1,000 per call. reason "import" makes the contact import mark them unsubscribed.
   for (let i = 0; i < suppressed.length; i += 1000) {
     const { error } = await unitpost.suppressions.create({
       emails: suppressed.slice(i, i + 1000),
       reason: "import",
     });
     if (error) throw new Error(error.message);
   }

3. 3

   Import the CSV

   In Contacts, choose Import CSV. Email, first and last name and your new unsubscribed column map on their own; check the mapping, and import other properties as custom fields. From a terminal: unitpost contacts imports create --file loops-audience.csv --custom-column "*".

4. 4

   Import mailing lists as topics

   Paste the Loops key in Settings → Migration. Each list becomes an opt-in topic, so nobody gets mail scoped to it yet.

5. 5

   Restore list membership

   These people opted in at Loops, so record it here. Filter the Loops audience by each list, download it, and for every address call PUT /api/v1/contacts/{email}/topics with { "topic_id": "top_…", "subscribed": true }. Unitpost has no bulk opt-in, by design.

6. 6

   Add and verify the domain

   Add the sending domain in Domains and publish the records shown: MX and SPF on unitpost.<your domain> and a DKIM TXT under _domainkey. Loops keeps its records on envelope, so both stay verified. Keep your single _dmarc record.

7. 7

   Rebuild transactional emails as templates

   Recreate each transactional email in the template editor. Every dataVariables key becomes a {{key}} placeholder filled from template.variables; first_name, last_name and email are reserved and fill from the contact. Set them to transactional and publish.

8. 8

   Switch the SDK

   transactionalId becomes the template's tmpl_ id and dataVariables becomes template.variables. Both APIs take an Idempotency-Key that lasts 24 hours.

   send.ts

   // Before: Loops
   import { LoopsClient } from "loops";
   const loops = new LoopsClient(process.env.LOOPS_API_KEY);
   await loops.sendTransactionalEmail({
     transactionalId: "clfq6dinn000yl70fgwwyp82l",
     email: "user@example.com",
     dataVariables: { loginUrl: "https://app.acme.com/login" },
   });
   
   // After: Unitpost
   import { Unitpost } from "unitpost";
   const unitpost = new Unitpost(process.env.UNITPOST_API_KEY);
   const { data, error } = await unitpost.email.send({
     from: "Acme <hi@mail.acme.com>",
     to: "user@example.com",
     template: { id: "tmpl_123", variables: { loginUrl: "https://app.acme.com/login" } },
   });

9. 9

   Recreate webhooks

   Loops signs webhook-id.webhook-timestamp.body with HMAC-SHA256 and a whsec_ secret; Unitpost signs the same three values, sent as svix-id, svix-timestamp and svix-signature. Rename the headers your verifier reads, use the new secret, and read the event name from type instead of eventName.

10. 10

    Test, move traffic, then cancel

    Send each template with POST /api/v1/email/templates/{id}/test-send and fire POST /api/v1/webhooks/{id}/test. Move transactional mail first, then campaigns, and cancel Loops once the checks below are done.

Before you cancel Loops

• Download a fresh audience CSV, plus one per mailing list; Loops has no API to list contacts later.
• Re-run the suppression check on addresses added since your first export.
• Note every workflow and the event that triggers it, so the emails they sent are covered in your code.
• Delete Loops' records on the envelope subdomain and its DKIM records once no mail goes through Loops. Keep _dmarc and Unitpost's records.
• Turn off Loops webhooks and revoke its API keys.

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