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.

Automated tools vs. custom API migrations

When planning your move, you will likely evaluate third-party services like Help Desk Migration alongside Help Scout's native importer and custom API scripts. A common question is regarding Help Desk Migration automated tool reliability when dealing with complex setups.

Overview: automated tool strengths and typical limits

Automated migration tools are excellent for standard, out-of-the-box helpdesk setups. If your source data consists mostly of standard tickets, basic customer profiles, and standard replies, these tools offer a fast, no-code path.

However, when asking if a helpdesk migration tool supports customization, the answer is nuanced. Automated tools typically struggle with custom fields heavy customization migration. They rely on lowest-common-denominator API mappings. If your source system relies on nested objects, highly specific relational data, or non-standard field types, automated tools often drop data silently or force awkward mappings (like dumping structured data into a single text note).

Compatibility matrix: custom fields & custom objects

Use this matrix to determine if an automated tool can handle your specific custom data scenarios or if a custom-scripted approach is required.

Scenario	Automated Tool Support	Custom Script / Managed Migration Required?
Basic custom fields (text, dropdowns)	Yes (usually 1:1 mapping)	No
High custom field count (50+ fields)	Partial (often hit mapping limits or API timeouts)	Yes, for reliable batching and mapping
Nested / Custom objects (e.g., Jira issues linked to tickets)	No (flattened or dropped)	Yes, requires custom relational logic
Large attachments (>10 MB)	No (silently dropped by target API)	Yes, requires external storage linking
Long tags or heavy tag counts	Partial (target system limits apply)	Yes, requires pre-processing/truncation
Inline images	Partial (often broken if source requires auth)	Yes, requires downloading and re-uploading

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 & run a 100-ticket pilot test

Create an API key (requires Admin role) with the appropriate scopes for the migration environment. Whether you use an automated tool or a custom script, you must run a structured pilot. Select 100 tickets representing your messiest, most complex edge cases (e.g., tickets with 50+ replies, inline images, heavy custom field usage, and multiple attachments).

Pilot test plan (100-ticket checklist):

• Custom fields: Check 10 tickets with heavily populated custom fields. Pass: All fields map to the correct Help Scout custom field. Fail: Data is missing, truncated, or dumped into a generic note.
• Timestamps: Verify the createdAt dates on the oldest and newest threads. Pass: Dates match the source system exactly. Fail: Threads show the date of the import.
• Inline images & attachments: Open 5 tickets known to have large attachments and inline screenshots. Pass: Images render in the thread; attachments download successfully. Fail: Broken image icons; missing files.
• Custom objects / Relational data: If migrating linked data (e.g., company profiles or linked orders). Pass: Data is correctly associated with the Help Scout Customer or custom field. Fail: Links are broken or missing.
• Agent assignment: Check tickets owned by inactive/legacy agents. Pass: Correctly assigned to the mapped legacy user in Help Scout. Fail: Assigned to the API admin or unassigned.

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

When to choose custom-scripted or managed migration

If your pilot test fails on custom fields, attachments, or relational data, an automated tool will not suffice. You should opt for a custom-scripted or managed migration when:

• You have a custom fields heavy customization migration where data fidelity is critical to your reporting or workflows.
• You need to clean, transform, or deduplicate data mid-flight (e.g., merging duplicate contacts before they hit Help Scout).
• You have attachments over 10 MB that need to be programmatically uploaded to external storage (like AWS S3) and linked in the ticket notes.
• You are migrating millions of records and require strict API rate-limit management, checkpoint logging, and delta syncs to ensure zero downtime.

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.

Next steps and consultation offer

Migrating a helpdesk is rarely just a copy-paste exercise. If your source data is heavily customized, relying on standard automated tools introduces a significant risk of silent data loss.

Next steps:

1. Audit your source system's custom fields and objects.
2. Map out exactly what needs to survive the move.
3. Run a strict 100-ticket pilot using the checklist above.

If your pilot reveals that off-the-shelf tools can't handle your data fidelity requirements, we can help.