Help Scout Migration Checklist

If you're preparing to migrate into Help Scout, this checklist walks you from planning, through pre-migration setup, into the data import itself, and finally through the post-go-live checks that keep everything clean.

Scope the migration

Get aligned on what you are migrating and why.

• Decide how far back you go Choose whether you are migrating two years, five years or your entire ticket history. Help Scout handles long histories well, but older tickets may not add real value.
• Identify which agents must exist in Help Scout before import Include all active agents and any legacy agents whose names appear on historic tickets. Correct ownership makes validation easier.
• Choose the objects you will migrate Conversations, threads, customers, companies, attachments, tags, custom fields and notes. Keep your list focused on what your team will actually use.
• Decide what you will intentionally skip Old spam, test tickets, deprecated tags, duplicate contacts or irrelevant archives. Removing noise upfront creates a cleaner Help Scout environment post-migration.
• Map old fields and structure to Help Scout Document how statuses, priorities, folders, custom fields, tags, and agent assignments from your old system translate into Help Scout's model. This mapping document becomes your single source of truth and prevents misalignment during import.

Migratable object matrix

Before diving into the details, this table gives you a single view of every object type and how it moves into Help Scout.

Object	Migratable via API	UI Setup Required First	Data Fidelity Risk	Notes
Customers	Yes	No	Low	Anchor of the data model. Supports merge, multiple emails, phone, social handles.
Companies	Yes	No	Low	Can be linked to customers via API.
Conversations	Yes	Mailbox must exist	Low	Each legacy ticket becomes one Conversation.
Threads (email, reply, note)	Yes	Parent conversation must exist	Medium	Timestamp fidelity depends on providing createdAt. See caveats below.
Attachments	Yes	No	Medium	10 MB per file limit. Base64-encoded on upload. Large files (logs, videos) will be rejected silently.
Tags	Yes	No	Low	Can be applied to both customers and conversations.
Custom Fields	Yes (populate only)	Fields must be created in UI first	Medium	API cannot create field definitions — only write values to existing fields. Fields missing at import time cause silent data loss.
Mailboxes	Read only	Yes — manual creation	N/A	Cannot be created via API. Must exist before any conversation import.
Folders	Assign only	Yes — manual creation	Low	Conversations can be assigned to existing folders.
Workflows / Automations	No	Yes — manual creation	N/A	Entire automation engine is UI-only.
Saved Replies	No	Yes — manual creation	N/A	Must be recreated by hand.
Beacon config	No	Yes — manual creation	N/A	Styling, placement, behaviour — all UI.
Users / Teams / Roles	No	Yes — invite via UI	N/A	Agent IDs are needed for conversation assignment, so users must exist before import.

What can be migrated via API into Help Scout

Help Scout's Mailbox API 2.0 is reliable and predictable. Once you understand how it models conversations and threads, you can rebuild almost everything from your old system inside Help Scout with accuracy.

Customers & companies

Customers are the anchor of the Help Scout data model. You can create customers, update their profiles, merge duplicates and attach phone numbers, emails and social handles. You can also create or update companies and link customers to them. This gives you the flexibility to bring over full CRM-style context from your old helpdesk.

Conversations & threads

Every historical ticket becomes a Conversation in Help Scout. Within each conversation, every message, note or automated event becomes a Thread. The API lets you create:

• Email threads
• Customer replies
• Agent replies
• Private notes
• Imported messages (with preserved timestamps when provided through the createdAt field)

This means you can neatly reconstruct the entire timeline of a ticket exactly as it originally happened.

Attachments

Help Scout supports file uploads through the API. You can attach files to threads, rebuild inline images and bring over documents with their filenames and MIME types intact. The per-file limit is 10 MB. Files are uploaded as Base64-encoded payloads. Attachments exceeding the limit are rejected silently — the thread is created but the file is dropped. Test your largest source attachments in the pilot import.

Tags & custom fields

Tags can be created and applied to customers and conversations. You can also populate Custom Fields on conversations if your mailbox has them configured ahead of time. This is where you store extra metadata like product name, issue category, priority or legacy ticket ID.

Mailboxes & folders (limited)

You can read mailboxes and folders via API, but you cannot create new ones programmatically. However, you can assign conversations to folders if they already exist.

Users & assignment

You can assign conversations to users, change status (Active, Closed, Pending) and apply workflows post-migration. Help Scout's API lets you link a thread to an agent ID, which is enough to preserve ownership for historic work.

What still needs to be configured in the Help Scout UI

This is where most teams trip up. Help Scout gives you a strong API, but a lot of the structural parts of the workspace must be configured by hand.

Mailboxes & email channels

Every mailbox (Support, Billing, Returns, Success) must be set up manually.

You need to connect each email address, verify forwarding, and configure the mailbox settings. None of this can be created from the API.

Users, teams & roles

Inviting agents, setting roles (Admin, User, Light User) and building teams is done entirely in the UI. You'll want these ready before import so conversations can be assigned correctly.

Workflows & automations

Help Scout's automation engine lives in the UI. You'll set up:

• Auto-assignment rules
• SLA and time-based rules
• Conditional workflows
• Tagging and folder routing
• Drip or lifecycle workflows (if using Beacon + Messages)

These cannot be created via API, so rebuild them manually after you import history.

Custom fields & mailbox-level settings

Before you import anything, create custom fields in the UI. The API can only populate fields that already exist. You'll also configure mailbox-level settings like:

• Default statuses
• Outbound signatures
• Auto-reply settings
• Custom folder structures

Saved replies

Saved Replies are UI-only. They help speed up agent replies, but they must be created manually.

Beacon configuration

If you use Beacon (Help Scout's chat/help widget), all styling, placement and behaviour are configured in the UI. The API cannot provision or configure it.

Help Scout's native import tool vs. API

Help Scout offers a built-in import path for a handful of platforms (notably Zendesk, Freshdesk and some email clients). The native importer handles basic conversation and customer migration through a UI wizard — no code required.

Where it falls short:

• Limited object coverage. Custom fields, tags, and company associations are often dropped or partially mapped.
• No timestamp control. You cannot provide createdAt values, so historical ordering may be lost.
• No batching or error recovery. If the import fails partway through, you have no programmatic way to resume or inspect what was missed.
• No delta sync. There is no mechanism to capture records created after your initial export.

For small, simple migrations (under a few thousand conversations, no custom fields, no attachment-heavy history), the native tool can save time. For anything larger or more complex, the API is the only path that gives you full control over data fidelity.

Pre-migration setup in Help Scout

This phase decides whether your import is peaceful or painful.

1. Create mailboxes and connect channels

Start by creating all your mailboxes in Help Scout: one for each email address or team that needs to handle conversations.

Connect your email channels, set up forwarding, verify DNS records if needed.

Don't point your production email traffic to Help Scout yet. Just make sure everything is ready. 2. Add users, teams and roles

Invite all agents who need to access Help Scout, including legacy owners if their names appear on old tickets.

Assign roles, create teams and check permissions. Ensure each agent's Help Scout ID is mapped properly in your migration script. 3. Create custom fields and folders

If your source system has structured data recreate those fields inside each mailbox.

Set up folders so migrated conversations can land in the right places. For example: "Urgent," "Billing," or "Product Feedback." 4. Pause noisy automation

Disable auto-replies, SLAs, notification-heavy workflows and any triggers that might activate during import. This keeps your agents' inboxes calm and prevents customers from receiving emails about old tickets. 5. Generate API keys & test a pilot import

Create an API key (requires Admin role) with the appropriate scopes for the migration environment. Run a small pilot file: a few dozen customers, a few tickets with attachments, some tags, and custom fields.

Inspect the results in Help Scout:

• Are threads ordered correctly?
• Do attachments open?
• Are statuses correct?
• Are customers properly linked?
• Are createdAt timestamps rendering as expected?

Fix anything now; it's a lot more painful later.

Migration execution

Once everything is set up, the migration engine takes over. The migration engine is whatever tool or script performs the actual API calls — whether that's a custom-built importer, a third-party service, or a managed migration provider.

First run a sample migration of a small dataset of the messiest data you can find.

Verify if the sample migration was successful and adjust the mapping and fix the script bugs before the full migration.

Then start by importing customers and companies if they are not already in your workspace. Then migrate conversations mailbox by mailbox.

Each legacy ticket becomes a Help Scout conversation with properly sequenced threads.

Track your API usage and errors. If you hit rate limits (HTTP 429), throttle your importer and implement exponential backoff.

When your full migration is done, run a delta import to capture anything created after your initial export. A delta import means re-exporting only records created or modified in the source system since your last export timestamp, then importing only those net-new or updated records into Help Scout. This closes the gap between your initial data pull and the moment you cut over.

Finally, switch over your email routing so new messages flow into Help Scout. At that moment, your agents officially move in.

Common API errors during Help Scout migration

These are the errors that come up most frequently when importing data via the Help Scout API.

Error	When It Occurs	Resolution
429 Too Many Requests	Importer exceeds 400 calls/minute rate limit	Implement exponential backoff. Add a delay between batches. Monitor Retry-After header.
422 Unprocessable Entity — invalid createdAt	Timestamp is malformed, empty string, or outside acceptable range	Validate all dates to ISO 8601 before sending. Fall back to a sensible default (e.g., source system's created date) rather than omitting the field.
404 Not Found — mailbox or user ID	Conversation references a mailbox or assignee that doesn't exist in Help Scout	Ensure all mailboxes are created and all agents are invited before import. Cross-check your ID mapping table.
400 Bad Request — attachment too large	File exceeds the 10 MB per-attachment limit	Pre-filter attachments by size. Log oversized files for manual review. Consider linking to external storage instead.
422 Unprocessable Entity — custom field not found	API tries to write a value to a custom field that hasn't been created in the mailbox	Create all custom fields in the UI before starting the import. This is the most common cause of silent data loss.
401 Unauthorized	API key is invalid, expired, or lacks required scopes	Regenerate the key with Admin-level access. Confirm the key's scopes match the endpoints you're calling.
409 Conflict — duplicate customer	Customer with the same email already exists	Use the Search API to check for existing customers before creating. Merge duplicates post-import if needed.

Rollback and recovery

If the migration fails partway through or corrupted data is discovered after a full import, you need a defined recovery path.

• Before you start: Take a full export of any existing Help Scout data (if this isn't a fresh instance). Document the exact state of every mailbox — conversation counts, customer counts, custom field configurations.
• Checkpoint logging: Your importer should log every successfully created record (conversation ID, customer ID, thread ID) with the corresponding source system ID. This lets you resume from the last successful point rather than restarting.
• Partial failure: If the import stops at 60%, use your checkpoint log to identify exactly which records were created. You can then resume from the next record without duplicating data.
• Full rollback on a fresh instance: If Help Scout is a new instance with no production data, the cleanest rollback is to delete the mailboxes and recreate them, then re-run the import after fixing the root cause. Help Scout does not offer a bulk-delete API for conversations, so manual cleanup of a partially imported mailbox is painful.
• Full rollback on an existing instance: If you imported into a mailbox that already had production data, isolate migrated records using a tag or custom field applied during import (e.g., migrated: true). This lets you identify and manually remove bad records without touching production conversations.
• Keep the old system in read-only mode for at least one to two weeks after cutover. It serves as your authoritative fallback if records are missing or corrupted.

Post-migration checklist

Data verification

Check every major count: conversations, customers, companies, attachments, tags.

Open a sample from different years and different queues. Make sure nothing looks odd. Incorrect timestamps, mis-threaded messages, missing attachments or broken ownership.

Channel & mailbox testing

Send a real email into each mailbox. Make sure it appears quickly and routes as expected.

Reply from Help Scout and ensure the customer reply threads correctly.

Test your folders, views and custom fields.

Agent readiness

Confirm each agent can see their mailboxes, reply to customers, add notes, assign conversations and use the correct folders.

Have them test Saved Replies, collision detection and workflows.

Automation & workflows

Turn your workflows back on, one at a time.

Test common workflows manually: auto-assign, tagging logic, SLA rules, escalation logic.

Verify that outbound messages work if you are using Beacon.

Final cutover & cleanup

Once everything looks solid, disable your old system or put it in read-only mode so no new tickets appear there. Document any anomalies.

Schedule a review after one week and again after one month to evaluate performance, agent comfort and any missed tickets.

Common mistakes

• Automations left on during import Help Scout workflows are powerful. If they stay active during migration, they might auto-reply, escalate, reassign or notify agents as every historic conversation is imported. Turn them off early and turn them on only after validation.
• Agent mapping errors Missing or mis-mapped agents result in incorrect ownership across hundreds of tickets. Create all necessary agents ahead of time and maintain a clean mapping table from old IDs to Help Scout user IDs.
• Custom fields created too late Help Scout's API can only populate fields that already exist in the mailbox. If they are missing, your importer will either fail silently or drop data. Build all custom fields ahead of import.
• Ignoring attachment limits Files exceeding the 10 MB per-attachment limit are silently dropped. Test the largest attachments from your source system before running a full migration.
• Skipping agent training Help Scout looks simple, but workflows differ from typical ticketing systems. Agents need a quick onboarding on folders, collision detection, Saved Replies, workflows and customer profiles to avoid confusion at go-live.
• Rushing the cutover Always keep the old helpdesk available in read-only mode for at least one to two weeks after going live in Help Scout. It gives agents a safety net for unusual conversations that didn't migrate cleanly.
• Not validating with enough samples Validate history across multiple years, teams and ticket types. Spot-check timestamps, attachments, agent ownership and custom fields. The more varied your sample, the smoother your final import.