> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration Guide

> How to migrate to Sequenzy without disrupting your existing email setup

# Migrating to Sequenzy

Switching email platforms can feel risky. You don't want to mess up communications with your existing audience. This guide walks you through a safe, incremental migration that minimizes risk while letting you start benefiting from Sequenzy immediately.

## The Migration Philosophy

Don't do a big-bang migration. Instead:

1. **Start small** - Begin with transactional emails
2. **Prove the system** - Verify deliverability and tracking work
3. **Expand gradually** - Add sequences for new users
4. **Complete the switch** - Move your existing audience last

This approach means you're never "all-in" until you're confident everything works.

## Phase 1: Transactional Emails

**Risk: Minimal** — These are one-off emails you control completely.

Start by moving your transactional emails to Sequenzy. These are the easiest to migrate because:

* They're triggered by your code, so you control when the switch happens
* Each email is independent, no sequences to worry about
* If something goes wrong, you can quickly revert

### What to Move First

Pick 2-3 low-stakes transactional emails:

```
✓ Welcome email (new signups)
✓ Password reset
✓ Email verification

Later:
  Order confirmation
  Payment receipts
  Shipping notifications
```

### Step-by-Step

**1. Create templates in Sequenzy**

Build your transactional email templates in the dashboard. Use the same content you currently have—don't redesign yet.

**2. Set up your sending domain**

Add and verify your domain in Settings → Domains. This takes a few hours for DNS propagation.

**3. Update your code**

Replace your current email sending with Sequenzy API calls:

```javascript theme={null}
// Before: Using your old provider
await oldProvider.send({
  to: user.email,
  template: "welcome",
  data: { name: user.name },
});

// After: Using Sequenzy
await fetch("https://api.sequenzy.com/api/v1/transactional/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SEQUENZY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: user.email,
    slug: "welcome",
    variables: { firstName: user.name },
  }),
});
```

**4. Run both systems in parallel (optional)**

For extra safety, send from both systems for a week:

```javascript theme={null}
// Send from both during transition
await Promise.all([
  oldProvider.send({ to: user.email, template: "welcome" }),
  sequenzy.send({ to: user.email, slug: "welcome" }),
]);
```

Watch deliverability metrics on both. When you're confident, remove the old provider.

**5. Monitor and iterate**

Check Sequenzy analytics:

* Are emails being delivered?
* Are open rates comparable to your old system?
* Any bounce issues?

### How Long: 1-2 weeks

Get comfortable with the API, verify deliverability, build confidence.

***

## Phase 2: Sequences for New Users

**Risk: Low** — Only affects people who haven't received your old emails yet.

Now that transactional emails are working, set up automated sequences for new subscribers.

### Key Insight

New users have no expectation of your old email patterns. They won't notice or care that you switched platforms. This makes them perfect for testing your new sequences.

### What to Build

**Onboarding Sequence**

```
Trigger: New signup (tag: "new-signup")
    │
    ▼
Day 0: Welcome email
    │
    ▼
Day 2: Getting started tips
    │
    ▼
Day 5: Feature highlight
    │
    ▼
Day 7: Success story / case study
```

**Post-Purchase Sequence**

```
Trigger: Purchase event (saas.purchase)
    │
    ▼
Day 0: Thank you + receipt
    │
    ▼
Day 3: Getting the most from your purchase
    │
    ▼
Day 7: Feedback request
```

**Trial Nurture Sequence**

```
Trigger: Trial started (saas.trial_started)
    │
    ▼
Day 0: Trial welcome
    │
    ▼
Day 3: Key feature walkthrough
    │
    ▼
Day 7: Trial halfway check-in
    │
    ▼
Day 12: Trial ending soon
    │
    ▼
Day 14: Trial expired + offer
```

### Step-by-Step

**1. Map your triggers**

Identify when you want sequences to start:

```javascript theme={null}
// On user signup
await sequenzy.subscribers.create({
  email: user.email,
  firstName: user.firstName,
  tags: ["new-signup"],
  enrollInSequences: true,
});

// On purchase
await sequenzy.events.trigger({
  email: user.email,
  event: "saas.purchase",
  properties: { plan: subscription.plan },
});
```

**2. Build the sequences**

Use the visual editor to create your flows. Start simple—3-5 emails max.

**3. Connect your app**

Add API calls at the right moments:

```javascript theme={null}
// During signup flow
async function handleSignup(user) {
  // Create user in your database
  await createUser(user);

  // Add to Sequenzy
  await fetch("https://api.sequenzy.com/api/v1/subscribers", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SEQUENZY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      email: user.email,
      firstName: user.firstName,
      lastName: user.lastName,
      tags: ["new-signup"],
      customAttributes: {
        userId: user.id,
        signupSource: user.source,
      },
    }),
  });
}
```

**4. Let it run**

Watch the sequences in action. Check:

* Are emails sending at the right times?
* Are conditions working correctly?
* What are open/click rates?

### How Long: 2-4 weeks

Build sequences, let them run with real users, iterate based on data.

***

## Phase 3: Migrate Your List

**Risk: Medium** — Now you're touching existing subscribers who may notice changes.

Once sequences are working for new users, import your existing subscriber list.

### Before You Import

**Clean your list first**

Don't import garbage:

```
Remove:
  ✗ Hard bounces
  ✗ Spam complaints
  ✗ Unsubscribed (unless legally required to track)
  ✗ Inactive 2+ years
  ✗ Invalid email formats
```

**Preserve subscription preferences**

Export status from your old system:

* Subscribed vs unsubscribed
* Subscription dates
* Tags/segments

### Import Strategy

**1. Export from old system**

Get a CSV with:

```
email,firstName,lastName,status,createdAt,tags
john@example.com,John,Doe,active,2023-01-15,"customer,newsletter"
jane@example.com,Jane,Smith,unsubscribed,2022-06-20,"churned"
```

**2. Import to Sequenzy**

Use the dashboard import or API:

```javascript theme={null}
// Bulk import via API
for (const subscriber of subscribers) {
  await fetch("https://api.sequenzy.com/api/v1/subscribers", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SEQUENZY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      email: subscriber.email,
      firstName: subscriber.firstName,
      lastName: subscriber.lastName,
      status: subscriber.status,
      tags: subscriber.tags.split(","),
      customAttributes: {
        importedAt: new Date().toISOString(),
        legacyId: subscriber.id,
      },
    }),
  });
}
```

**3. Verify the import**

Check counts match:

* Total subscribers
* By status (active vs unsubscribed)
* By key tags (customers, trial, etc.)

### Preserving Your Reputation

Your sender reputation is tied to your domain, not your email provider. As long as you're using the same sending domain, your reputation carries over.

If you're setting up a new domain:

* Warm it up gradually
* Start with your most engaged subscribers
* Increase volume over 2-4 weeks

### How Long: 1 week

Import is usually quick, but budget time for verification.

***

## Phase 4: Move Marketing Campaigns

**Risk: Higher** — Bulk emails to your full list.

This is the final step. You've proven the system works with transactional emails, sequences, and your imported list.

### Strategy: Don't Recreate Everything

You don't need to move every old campaign. Focus on:

```
✓ Move: Ongoing campaigns (newsletter, product updates)
✓ Move: High-performing templates
✓ Archive: One-time campaigns that won't repeat
✓ Rebuild: Underperforming campaigns (chance to improve)
```

### Running Your First Campaign

**1. Start with your most engaged segment**

Don't blast your entire list. Send to subscribers who:

* Opened an email in the last 30 days
* Are tagged as "engaged" or "active"
* Have been customers for 6+ months

```
Recipients: Filtered
Tags: contains "engaged"
Added: more_than 30 days ago
```

**2. Use a familiar format**

Your first campaign should look like your previous emails. Don't redesign—subscribers should feel continuity.

**3. Monitor closely**

Watch metrics in real-time:

* Bounces (should be \< 2%)
* Complaints (should be \< 0.1%)
* Opens (should match historical rates)

### Sunsetting Your Old System

Once you've sent 2-3 successful campaigns:

1. **Stop sending from old system** — Sequenzy is now primary
2. **Keep old system in read-only** — For historical data access
3. **Update any integrations** — Webhooks, Zapier, etc.
4. **Cancel old subscription** — After 30-60 days of success

### How Long: 2-4 weeks

Build confidence with engaged segments before expanding.

***

## The Complete Timeline

| Week | Phase         | Focus                                        |
| ---- | ------------- | -------------------------------------------- |
| 1-2  | Transactional | Set up domain, move 2-3 transactional emails |
| 3-4  | Sequences     | Build onboarding + post-purchase sequences   |
| 5    | Import        | Migrate subscriber list                      |
| 6-7  | Campaigns     | First campaigns to engaged segments          |
| 8+   | Complete      | Full migration, sunset old system            |

**Total: 6-8 weeks** for a careful migration.

***

## Migration Checklist

### Before Starting

* [ ] Export full subscriber list from old provider
* [ ] Document your current email templates
* [ ] List all triggered/transactional emails
* [ ] Map your subscriber tags/segments
* [ ] Note any integrations (Stripe, Zapier, etc.)

### Domain Setup

* [ ] Add sending domain in Sequenzy
* [ ] Configure DNS records (SPF, DKIM, DMARC)
* [ ] Verify domain
* [ ] Create sender profiles

### Transactional Emails

* [ ] Create transactional templates
* [ ] Update API calls in your code
* [ ] Test with internal emails
* [ ] Monitor deliverability for 1 week

### Sequences

* [ ] Design sequence flows on paper first
* [ ] Build sequences in dashboard
* [ ] Connect triggers in your code
* [ ] Test with new signups
* [ ] Monitor for 2 weeks

### List Import

* [ ] Clean your list (remove bounces, spam complaints)
* [ ] Export with all fields and tags
* [ ] Import to Sequenzy
* [ ] Verify counts match
* [ ] Check tag assignments

### Campaigns

* [ ] Send first campaign to engaged segment
* [ ] Monitor metrics closely
* [ ] Gradually expand to full list
* [ ] Update any automation tools

### Cleanup

* [ ] Disable sending from old provider
* [ ] Update webhook URLs
* [ ] Document new system for team
* [ ] Cancel old provider subscription

***

## Common Migration Pitfalls

### 1. Moving Too Fast

**Problem:** Migrating everything at once, something breaks, scrambling to fix.

**Solution:** Follow the phased approach. Each phase should run smoothly before moving on.

### 2. Not Cleaning Your List

**Problem:** Importing old bounces and spam traps tanks your reputation.

**Solution:** Clean before importing. Remove anyone who hasn't engaged in 2+ years.

### 3. Changing Design During Migration

**Problem:** Subscribers notice dramatic changes, engagement drops, you can't tell if it's the new platform or new design.

**Solution:** Keep designs identical during migration. Redesign after you're settled.

### 4. Losing Subscriber Preferences

**Problem:** Subscribers who unsubscribed start getting emails again.

**Solution:** Export and respect subscription status. Never email someone who opted out.

### 5. Not Monitoring

**Problem:** Issues go unnoticed until they're serious.

**Solution:** Check metrics daily during migration. Set up alerts for bounces and complaints.

***

## Need Help?

Migration questions? Reach out:

* **Email:** [nic@sequenzy.com](mailto:nic@sequenzy.com)
* **Twitter:** [@nikpolale](https://x.com/nikpolale)

We've helped many teams migrate and are happy to review your migration plan.