If you're preparing to migrate into Help Scout, it’s worth slowing down for a moment and getting a proper plan in place. Help Scout feels simple on the surface, but its data structure means you need to be deliberate.
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. This section sets the tone for the entire project, and teams that get this part right always end up with a calmer go-live.
- 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.
What can be migrated via API into Help Scout
Help Scout’s API 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. It’s straightforward as long as you stay within file-size limits.
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.
Pre-migration setup in Help Scout
This phase decides whether your import is peaceful or painful. When teams skip this, they pay for it later. When they follow it, the migration tends to run calmly.
- 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. - 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. - 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.” - 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. - Generate API keys & test a pilot import
Create an API key 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?
Fix anything now; it’s a lot more painful later.
Migration Execution (Let the migration team do the heavy lifting)
Once everything is set up, the migration engine takes over.
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, throttle your importer.
When your full migration is done, run a delta import to capture anything created after your initial export.
Finally, switch over your email routing so new messages flow into Help Scout. At that moment, your agents officially move in.
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 and pro tips
After doing hundreds of Help Scout migrations, these are the pitfalls that show up the most and the small decisions that make the biggest difference.
- 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
Large files, logs and videos often exceed Help Scout’s attachment size limits. 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 a week 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.