Skip to content
⌘K
InboxAsk a human

Step 4: Creating your cutover plan

Updated by Dustin

Migrations have a well-earned reputation for being a messy, drawn-out affair — often, teams will be split across multiple tools and/or workflows during the switch, leading to confusion for both your customers and your team members. Therefore, efficiency and accuracy come at a premium when switching tools — despite this, we often see support leaders falling into the trap of treating the historical backfill and the live channel cutover as one giant event. The more moving pieces there are, the greater the chance is of something going wrong.

Plain makes this manageable by separating the two completely. You can kick off your historical backfill in the background — via one-click native importers, a scoped GraphQL API worker, or a hybrid of both — and build out your routing, SLAs, and workflows in parallel while the data pours in.

What good looks like

Ideally, you’ll want a migration where your historical backfill doesn’t block the rest of your workspace configuration, and your live cutover happens in a predictable weekday window:

  • Decoupled backfill: Your historical threads are syncing in the background (either a full native backfill or a scoped 6-12 month API import) while you build out your channels, routing, SLAs, and workflows in parallel

  • Pre-populated account graph: Your teammates and explicit CRM/backend accounts are synced into Plain before the thread import runs, so historical tickets populate with their assignees, customers, and accounts intact

  • A written cutover sequence (with a hard coexistence rule): Every mailbox and Slack cohort has a scheduled cutover window, an owner in IT/DNS, and a single rule for where agents work in-flight conversations to mitigate the risk of double replies

The three architectural calls to make upfront

Before moving ahead with import, make sure to lock in these three decisions with your ops and engineering leads leading up to the cutover date:

1. Native importer vs. scoped API backfill (or a hybrid)

The first question teams typically have when planning out a migration is

  • When to use a native importer (Zendesk, Intercom, Front, Help Scout, Freshdesk): You want a zero-engineering background sync of all threads, messages, customers, internal notes, and tags-as-labels. Runs of 100k+ threads typically finish in 24-72 hours and continue polling hourly for new messages until you turn them off.

Heads-up: confirming starts a full, unfiltered sync right away, and there's no easy undo (removing imported data later takes help from the Plain team or diving into the API), so make sure you want all of it in this workspace.

  • When to use the GraphQL API importer (custom ticket importer): You want to filter by cutoff date (createdAt >= 12 months ago), bring over custom ticket fields as structured thread fields, migrate attachments from Zendesk or Freshdesk, or pull from an unsupported/in-house system.

  • The hybrid play: Many scaling teams run the native importer for raw history and run a lightweight API script alongside it at cutover to stamp structured thread fields or reconcile statuses on open tickets. Both paths deduplicate by customer and externalId, so they won't collide.

Metadata synced

Zendesk

Freshdesk

Intercom

Help Scout

Front

Custom API (importThread)

Threads + messages + notes

✓

✓

✓

✓

✓

✓

Customers

✓

✓

✓

✓

✓

create first with upsertCustomer

Attachments

✗

✗

✓

✓

✓

✓

Labels (from tags)

✓

✓

✓

✓

✓

✓

Custom ticket fields → Thread fields

✗

✗

✗

✗

✗

✓ (separate upsertThreadField call)

Priority

✓

✓

✓

not stated

✗ (normal)

✓

Status

✓ (snapshot)

✓

✓

✓ (snapshot)

✓

✓

Assignee

if agent exists

✓

✓

if agent exists

✓

✓

2. The dependency trap: accounts and users must exist before threads arrive

This is the single most common gotcha in large migrations. In Plain:

  1. Account inference runs once, at the exact moment a thread is created or imported. If you import 200k tickets before syncing your Salesforce/HubSpot accounts and customer memberships, those threads won't retroactively attach to explicit accounts when you turn your CRM sync on later.

  2. Assignee matching on Zendesk and Help Scout requires existing Plain users. The importer matches legacy assignees to Plain teammates by email address and leaves the thread unassigned if that user hasn't been invited yet or has a Viewer role.

  3. Threads without a resolvable customer are skipped. If a legacy ticket belonged to a deleted user or a system alert with no email address, a native importer skips it. In a custom script, map it to a fallback customer that already exists.

The rule: Invite your roster and run your account + customer membership sync before you kick off your ticket backfill.

3. Single-window cutover vs. phased coexistence

Even with a dozen mailboxes and 300 Slack Connect channels, flipping all support channels in a single low-volume window is almost always less painful than a multi-week phased rollout. A single cutover followed by one final delta sync compresses your overlap to 1-2 days.

Phasing by cohort (billing@ and Tier 1 chat in Week 1, support@ and Enterprise Slack Connect in Week 2) is only worth the operational tax when change-management or IT constraints force your hand, or when other departments (like Finance or Legal) are staying behind in the old help desk permanently. If you have to coexist across tools for a week or two, enforce one non-negotiable floor rule:

The coexistence ownership rule: Never let agents work out of two tools for the same view. The moment a mailbox or Slack channel cohort flips its forwarding to Plain and you run its final delta sync, 100% of open and new conversations for that cohort should be worked on inside of your Plain workspace, including replies to in-flight threads that started in the legacy tool. Turn off all outbound triggers and auto-responders for that cohort in the old tool the same minute you flip forwarding.

The execution sequence

Run your migration in four stages so you can build and validate your workspace in parallel without freezing your frontline team:

Stage 1: Rehearse in Sandbox and pre-populate your object graph

If you want to pressure-test your API import worker, workflow library, and SLA rules without touching production data, ask Plain support in Slack or at help@plain.com to spin up a Sandbox workspace first.

Once you're ready in production:

  1. Invite your support roster so user emails exist for assignee matching

  2. Run your initial CRM sync or upsertAccount + addCustomerToAccounts worker so explicit accounts exist before threads reference them

  3. Create your target label taxonomy and thread field schemas if your import script maps legacy tags and custom fields

Stage 2: Kick off the background backfill

For a fuller walkthrough of the native importers, see Step 4: Migrating to Plain — import or fresh start? in our small-team series.

  • For a native importer: Head to Settings → Integrations, select your legacy help desk under Importers, connect your account, and confirm the import. It will begin backfilling in bulk (and won't fire any SLAs, auto-responders, or workflows).

    Open your support tool under Importers, then select Connect with Zendesk Importer to review what the import will do.
  • For a custom API worker: Don't burn a sprint writing boilerplate from scratch — hand Cursor or Claude Code our GraphQL schema, the Importing threads guide, and a machine user API key holding thread:import (plus customer:create and tenant:read), and have it generate an idempotent worker with --dry-run and --limit flags.

    Create a machine user and give it the thread:import permission before you create its API key.

Every API-imported thread uses two mutations — importThread (which automatically sets isBackfill: true so no automations fire) and importThreadMessages (which batches up to 25 messages / 5 MiB per call):

mutation { importThread(input: { customerIdentifier: { emailAddress: "priya@acme.com" } externalId: "zd-88123" title: "Compute us-east-1: p99 latency above threshold" priority: 2 status: DONE statusDetail: { type: DONE_MANUALLY_SET } createdAt: "2026-06-02T09:14:00Z" }) { thread { id } } } mutation { importThreadMessages(input: { threadId: "th_01J..." messages: [{ externalId: "zd-msg-88123-1" type: INBOUND text: "Still seeing 502s after the restart." createdAt: "2026-06-02T09:14:00Z" emailMessageId: "<CAF9x...@mail.acme.com>" }] }) { thread { id } } }

Critical detail for in-flight email threads: Always populate emailMessageId from the original email's Message-ID header on every imported message. When a customer replies to an open email thread after you redirect forwarding to Plain, Plain matches their email's In-Reply-To / References headers against emailMessageId to stitch the reply onto the migrated thread instead of opening a brand-new ticket.

Stage 3: Build the rest of the workspace in parallel while the backfill runs

While the backfill chugs along in the background, feel free to move on and finalize your routing and SLA policies, publish your workflow library, and start integrating AI into your workspace.

Stage 4: Flip the cohort and run your delta pass

During your scheduled low-volume cutover window for a channel cohort:

  1. Redirect email forwarding in Google Workspace / Microsoft 365 to Plain's Postmark inbound address, and swap your Slack Connect / portal integrations over to Plain

  2. Disable all outbound email triggers, webhook automations, and auto-responders for that cohort in the legacy tool

  3. If you used a custom script, run one final delta pass of it. If you used a native importer, wait for its next sync, since there's no manual way to run one (and if you used Zendesk or Help Scout's native importer — which snapshots ticket status on initial import — run a quick API pass calling markThreadAsDone / markThreadAsTodo / assignThread for any tickets whose status changed in the old tool during the backfill window)

Verification checklist before you decommission the legacy queue

  • Run a 25-thread canary batch first: Run your script with --limit 25 and inspect those 25 threads in Plain — verify Customer, Account, Tier, Assignee, Labels, Thread fields, and message ordering. Because Plain deduplicates on customer and externalId, re-importing those 25 threads in the full run is safe to do.

  • Reconcile your counts: On native importers, open the importer under Settings → Integrations and compare the thread count in its sync history with the ticket count in your old tool to spot any tickets skipped due to missing customer emails.

  • Test in-flight email threading: Reply from an external email account to a thread that originated in your old tool after forwarding is pointed at Plain, and confirm the reply appends to the imported thread rather than creating a duplicate.

Troubleshooting/FAQ

Nothing has appeared in our workspace yet (or the 100k+ backfill is taking a long time).

Initial backfills process in bulk, and workspaces importing 100k+ threads typically take 24-72 hours to finish. Threads surface in batches as the job runs, and there isn't a live progress bar in the UI.

Try this: Open the importer under Settings → Integrations and check that its sync history shows a Running status, or ping Plain support in Slack or at help@plain.com for a backend ETA check.

Historical threads are missing (or landed with no Account attached) after the import finished.

Plain requires every thread to resolve to a customer, and it only runs account inference once — at the moment a thread is created or imported. Here are the two causes:

The legacy ticket had no resolvable customer email

  • System-generated tickets or tickets from deleted users with no email address can't resolve to a Plain customer and are skipped by native importers.

  • Try this: Compare the thread count in the importer's sync history under Settings → Integrations with the ticket count in your old tool. In a custom script, map deleted or system requesters to a fallback placeholder email before calling importThread.

The ticket backfill ran before explicit Accounts were synced

  • Because account inference doesn't re-run retroactively when a customer is added to an account later, importing threads before your CRM/API account sync leaves those historical threads unlinked.

  • Try this: Sync your accounts and customer memberships before running the full backfill. To repair threads that were already imported, have your LLM run a short batch script that queries those threads and calls updateThreadAccount.

Status or assignee changes made in Zendesk/Help Scout during the backfill week didn't carry over to Plain.

While a native importer is active, new messages on imported tickets continue to sync hourly, but ticket metadata (status, assignee, tags) is captured as a snapshot when the ticket is first imported.

Try this: Right after you flip forwarding for a cohort at cutover, run a short script that queries tickets updated in the last 7 days in your legacy tool and updates their status/assignee in Plain via the API so your team starts with an accurate Todo queue.

Customers are getting duplicate auto-replies (or replies from two tools) during coexistence.

Both your legacy help desk and Plain are actively listening and firing outbound rules on the same mailbox or Slack channel at the same time.

Try this: The moment a mailbox's forwarding rule points at Plain, disable all outbound triggers and auto-responders for that address in your legacy help desk, and make sure only one tool's bot is active in each Slack Connect cohort.

Customer replies to in-flight email tickets are opening brand-new threads in Plain instead of threading onto the migrated conversation.

When a customer replies to an email thread that started in your old tool, Plain matches the incoming email's In-Reply-To and References headers against the emailMessageId stored on the imported messages.

Try this: In your custom import script, pass the original email's Message-ID header as emailMessageId on every message in importThreadMessages. Because importThreadMessages deduplicates by externalId, re-running your script skips messages it already imported. To add a missing emailMessageId, re-run it across your open in-flight tickets with updateExisting: true on each message. That updates the existing message instead of duplicating it.