Migrate from Help Scout to FreeScout

Migrate from Help Scout to FreeScout: what the move involves

If your Help Scout renewal, pricing change or data residency concern is pushing you toward self-hosting, FreeScout is a self-hosted shared inbox that can take over most of the Help Scout workflow. The real work is not the software install. It is extracting conversations, threads, attachments and customers, re-creating mailboxes and saved replies, and deciding which paid modules you need for parity with your current plan. In most organizations an internal administrator owns the project, since they hold the Help Scout account, the mail domains and the decisions about who sees which mailbox. An implementation partner usually handles the server build, the mail flow (SMTP, IMAP or POP3, and OAuth for Microsoft 365 or Google Workspace), the extraction scripts and the test cutover. Confirm the split in writing with any partner, including who signs off on the data mapping and who runs backups after go-live.

Effort depends on how much history you must carry over and how many mailboxes, saved replies and integrations you run. Extraction through the Help Scout Inbox API 2.0 is rate limited by plan, so large archives take time to pull, and you should confirm current limits with Help Scout before estimating. Attachments and thread metadata often need a custom mapping step, and the FreeScout migration service or an API import should be tested on a copy of a single mailbox first. Ask any partner to show how they will verify counts and attachment integrity on that test run. The main risks are lost threads, broken links from your support widget, and email routing that changes during cutover. Plan a parallel period where both systems receive mail, decide whether closed history is imported or kept as a read-only archive, and check each module you still need, such as SAML SSO, LDAP, Knowledge Base or Workflows, against the FreeScout modules page before you cancel the Help Scout plan.

Which Help Scout capabilities map to FreeScout and where the gaps are

This table maps each Help Scout capability to its FreeScout equivalent and marks it as clean, needs rework or gap. Use it to find which items work out of the box, which need configuration or a paid module, and which need to be confirmed before you commit to a cutover date.

Help Scout capability	FreeScout equivalent	Status and what to check
Shared inboxes and mailboxes	Unlimited mailboxes with SMTP, IMAP and POP3 email integration, plus OAuth for Microsoft 365 and Google Workspace	Clean. Recreate each mailbox, then re-test forwarding, sending addresses and OAuth consent for each account.
Conversations and threads	Conversations and threads imported through the API or migration service	Needs rework. Confirm which thread types, internal notes and timestamps survive the import, and spot-check a sample of closed and reopened conversations.
Attachments	Attachments stored on the FreeScout server, with optional S3 storage through the free S3 Storage module	Needs rework. Confirm that attachments are downloaded during export and sized for your storage plan before import.
Saved replies	Canned responses created per mailbox in FreeScout	Needs rework. Saved replies are not part of the migration path, so recreate them by hand or script the copy from your export.
Customers and contact records	Customers imported with conversations, with profile fields stored in FreeScout	Needs rework. Map custom Help Scout fields to FreeScout customer fields and confirm duplicate handling for returning customers.
Docs and Beacon	Knowledge Base module (paid) for articles; Beacon has no direct one-to-one equivalent	Gap. Confirm which Docs collections and Beacon widgets you use, then plan the article migration and widget replacement separately.
SAML and SSO	SAML SSO module, sold as a paid lifetime license per instance	Needs rework. Budget the module purchase and confirm your identity provider works with the module before cutover.
API and webhooks	API and Webhooks module, sold as a paid lifetime license	Needs rework. Inventory every Help Scout API integration and webhook, since each one must be rebuilt against the FreeScout API or removed.
Reporting	Built-in reports are narrower than Help Scout reporting; no direct equivalent of every dashboard	Gap. Export historical data for reporting teams and confirm which metrics must be rebuilt in your BI tool.
Workflows, satisfaction ratings and time tracking	Workflows, Satisfaction Ratings and Time Tracking modules, each a paid lifetime license	Needs rework. Enable only the modules you actually used in Help Scout and confirm each one's behavior against your process.
Integrations (Zapier, Slack, Make)	Zapier and Make integrations linked from FreeScout, with channels such as Slack and live chat via modules or add-ons	Needs rework. Confirm each connector's current status and rebuild triggers that depended on Help Scout event names.

What data moves through the Help Scout Inbox API 2.0 and what needs rebuilding

Conversations, threads, attachments and customers can be pulled from Help Scout and loaded into FreeScout, but identities, mailbox routing, saved replies and integrations are configured again rather than copied. Each card marks one piece of that split, with the check to run before cutover.

Conversations, threads and attachments

Pull conversations, their threads and attached files through the Help Scout Inbox API 2.0, which uses OAuth 2 and is subject to plan rate limits. Large mailboxes can take many requests, so plan the pull in batches and keep a log of every conversation ID processed. Confirm that thread authors, timestamps and internal notes map to the matching FreeScout fields, and that attachments are stored and linked correctly after import.

Customers and contact records

Customer records carry the email addresses that anchor conversation history, so a mismatch here breaks threading for returning customers. Map name, email, phone, company and custom fields one by one, and decide how duplicate customers with several addresses are merged. Ask FreeScout's migration service or your import script to report how many customer records were created, updated and skipped.

Agent accounts and passwords

Agent identities do not carry over with their passwords. Recreate each agent in FreeScout, assign mailbox access and roles, and send password reset emails through the working SMTP configuration. Confirm that reset emails arrive before retiring Help Scout logins, because agents who cannot sign in on cutover day will block the queue.

Mailboxes and email routing

Each Help Scout mailbox must be recreated as a FreeScout mailbox with its own inbound and outbound settings. Choose IMAP or POP3 for inbound mail and SMTP for outbound, or configure OAuth for Microsoft 365 and Google Workspace. Test forwarding rules and DNS records for each address, then send a test message through every mailbox before changing the public address.

Saved replies and workflows

Saved replies and routing logic do not transfer through the API as working settings, so recreate them manually or through a scripted import. Export the Help Scout saved reply text, compare the variables and placeholders with FreeScout's template syntax, and confirm that signatures and auto-replies render correctly. Workflow rules that depend on Help Scout automation should be re-tested on sample tickets.

Integrations rebuilt through Zapier, Make or the API

Connections to Slack, CRMs, billing tools and internal systems must be rebuilt against FreeScout, using the API, Zapier or Make, or the webhook features in the paid API and Webhooks module. Inventory every Help Scout integration first, record the trigger and action it uses, and test each one against a staging instance. Any integration without an equivalent should be listed as an accepted gap before cutover.

The migration sequence from inventory to decommission

This sequence moves a Help Scout shared inbox to a self-hosted FreeScout instance in controlled stages, with a sign-off at each gate so that no mailbox goes live before its history, routing and saved replies have been checked. Help Scout is decommissioned only after an archive of the export has been verified.

Inventory mailboxes, customers, saved replies and integrations
The support operations lead works with the Help Scout administrator to list every mailbox, its forwarding addresses, the agents and teams that use it, saved replies, workflows, tags, customer fields and every connected channel or integration. The output is a data map that records each source object, the FreeScout destination, the module needed for parity (such as Knowledge Base, Workflows or API and Webhooks) and the owner who will verify it. The step is done when the data map has been signed off by the support operations lead and the security or compliance owner, who confirms which data categories are in scope.
Export conversations through the Inbox API
The Help Scout administrator creates the OAuth 2 credentials needed for the Inbox API and pulls conversations, threads, attachments and customers into a staging store that the migration team controls. The team records rate limits for the plan in use and schedules pulls around them, then checks counts per mailbox against the data map. The output is a raw export with a manifest of object counts and checksums per mailbox. The step is done when the export manifest reconciles with Help Scout's counts and the security owner has approved where the staging copy is stored.
Run a pilot import into a non-production FreeScout
The migration engineer installs FreeScout on a non-production host, follows the FreeScout migration service or an API import for one representative mailbox, and loads a sample of conversations with attachments and customer records. They compare threads, timestamps, assignees, attachments and customer merges against the export manifest and note what fails to map. The output is a validated pilot report listing each mismatch, its cause and the agreed fix. The step is done when the support lead accepts the report and the pilot is re-run until the remaining gaps are documented and accepted.
Rebuild mailboxes, saved replies and modules
The FreeScout administrator recreates the production mailboxes over SMTP, IMAP or POP3, configures OAuth for Microsoft 365 or Google Workspace where used, and rebuilds saved replies, folders and workflows from the data map. Modules that the team relies on, such as SAML SSO, LDAP Integration or Knowledge Base, are licensed and installed before users are added. The output is a configuration record that lists each mailbox, its connection settings, the modules installed and the saved replies imported. The step is done when a test agent has confirmed each mailbox sends and receives mail and the identity owner has signed off on access.
Test routing in a parallel run
For a defined period agreed in advance, the team forwards a copy of inbound mail to FreeScout while Help Scout stays live, and both systems are checked for duplicate or missing messages. The migration engineer tests threading, reply headers, deliverability of outbound mail and collision detection with real agents working test cases. The output is a routing runbook that records each forwarding rule, the expected result, the observed result and the rollback step. The step is done when the operations lead confirms that no message was dropped and the security owner approves the rollback plan.
Cut over forwarding and DNS
The mail administrator changes mailbox forwarding and any DNS records for MX, SPF, DKIM and DMARC so that inbound mail reaches FreeScout, and updates widget or form links that point to Help Scout. The change is made in the window in the cutover checklist, with the rollback steps ready and the agents informed. The output is a cutover checklist with each change, the time it was applied and a verification result. The step is done when the checklist is signed off by the infrastructure owner and the support lead, and inbound and outbound test messages pass.
Archive the export and decommission Help Scout
Once the parallel run and cutover have held, the team stores the verified export and its manifest in the archive location approved during inventory, with access limited to named roles and a retention period set by the compliance owner. Help Scout access is reduced, the subscription is ended according to its terms, and the team confirms that no mail still routes there. The output is an archive record with checksums and a decommission certificate listing the removed accounts and integrations. The step is done when the compliance owner accepts the archive and the business owner signs off the decommission.

How the email routing and parallel run work

The main risk in a parallel run is that customer email reaches both Help Scout and FreeScout and each system answers it. FreeScout receives mail through IMAP, POP3 or SMTP connections to its mailboxes, so the simplest design is to keep Help Scout as the only recipient of the public address while FreeScout reads a copy. Decide which system owns each mailbox for each day of the run, write that decision down, and confirm it with your mail provider before any agent starts replying in FreeScout. Mail forwarding rules, Google Workspace or Microsoft 365 delegation and any inbound rules in your provider's admin console all need to be listed, because a forgotten rule is the usual cause of duplicates. Collision detection in FreeScout helps agents avoid double answers during the period when both teams can see the same conversation. It shows when another user is viewing or editing a conversation, but it does not stop two systems from sending separate replies to the same customer. For that reason, agree a cutover rule such as one owner per mailbox and a hard date after which Help Scout stops sending. Test this with a seeded thread that uses a known test address, and check that the test message appears once in the intended system only. Record the result before you widen the run to live queues. Before switching any outbound mail, check SPF, DKIM and DMARC for the sending domain. Each new sending path, including FreeScout's SMTP settings, must be authorized in the SPF record and signed with a DKIM key that your DNS team controls, or replies may land in spam or fail DMARC alignment. Ask your mail administrator to confirm the current SPF include statements, the DKIM selectors and the DMARC policy, and to verify that forwarded mail is not rewritten in a way that breaks signatures. Confirm the exact configuration with your mail provider and your DNS records, since the setup differs between Microsoft 365, Google Workspace and self-managed mail servers.

What drives migration cost and duration

This table lists the cost components of moving from Help Scout to FreeScout, who is paid for each, whether it is one-time or recurring, and what pushes it up or down. Use it to shape the questions you put to any implementation partner before you sign a written scope.

Cost component	Who is paid or who pays	One-time or recurring	What drives it up or down
Discovery and inventory	Internal team or implementation partner	One-time	Number of mailboxes, shared folders, saved replies and workflows in use. Keep the inventory short by retiring stale mailboxes first.
Extraction scripting	Internal developers or implementation partner	One-time	Help Scout Inbox API 2.0 access, the plan's rate limits, and how many conversations and threads must be pulled. Rate limits depend on your Help Scout plan, so confirm them before scheduling.
Attachment transfer	Internal team or implementation partner for storage work	One-time, plus storage that recurs	Total attachment volume and file sizes. Large archives add transfer time and disk or object storage cost; FreeScout's S3 Storage module is free and can reduce local disk pressure.
Import and validation	Implementation partner or internal engineers	One-time	Custom fields, tags, customer records with duplicates and the choice between the migration service, an API import or both. Spot-check threads and attachments against the source.
Module licensing	FreeScout module publisher, paid per instance	One-time per instance, with lifetime updates	Which paid modules you need for parity, such as SAML SSO, LDAP, Knowledge Base, API and Webhooks, Workflows, Satisfaction Ratings or Time Tracking. Each module is licensed per FreeScout instance, so multiple instances multiply the cost. Confirm current terms on the modules page.
Hosting and infrastructure	Your cloud provider, data center or hosting vendor	Recurring	Expected traffic, storage growth, backups and redundancy requirements. Ask the partner to state the sizing assumptions in the quote.
Email configuration	Internal IT, DNS administrator or implementation partner	One-time setup, then ongoing mail operations	Number of mailboxes, SMTP, IMAP or POP3 connections, OAuth setup for Microsoft 365 or Google Workspace, and deliverability controls such as SPF, DKIM and DMARC.
Integrations and automations	Internal developers or implementation partner	One-time build, with maintenance	Zapier, Make, webhooks and API consumers that must be rebuilt against FreeScout. Each integration adds testing and upkeep.
Training and change management	Internal team or training provider	One-time, with onboarding for new agents	Number of agents, roles and how much of the Help Scout workflow must be replicated for staff.
Decommission and parallel running	Internal IT or implementation partner	One-time	Length of any overlap period with Help Scout, DNS and widget cutover, and the retention and deletion steps for exported data. Confirm your retention obligations before shutting down the source account.

What usually goes wrong and how to prevent it

Most failed help desk migrations lose history, routing or sending reputation rather than the software itself. The cards below cover the risks we see most often when moving Help Scout conversations into FreeScout, with the prevention step and the check to run before cutover.

Lost attachments on large threads

Attachments are the first thing to disappear when a pull stops partway through a long thread. Confirm that each conversation's thread count and attachment count match between Help Scout and FreeScout for a sample of your largest conversations, and keep the original export files until that sample passes. Store attachments in a location you control so a failed upload can be retried without re-pulling the whole account.

Incomplete customer merges

Help Scout customers can exist as several records for the same person after merges and email changes. If you import them without reconciling, FreeScout shows fragmented histories and duplicate contacts. Decide on a canonical email per customer before import, then compare conversation counts per customer after the load.

Broken email forwarding

Mailboxes only work once inbound mail reaches FreeScout, so forwarding rules pointing at Help Scout must be changed in a planned order. Test one mailbox end to end, sending from an outside address and confirming the ticket appears with the right mailbox and customer, before changing the rest.

SPF and DKIM misconfiguration

Outbound replies sent from FreeScout under your domain will land in spam if SPF and DKIM records do not authorize the new sending path. Publish the records your mail provider specifies, send test replies to a Gmail and a Microsoft 365 account, and read the authentication headers before routing live customer replies through FreeScout.

Duplicate replies during parallel run

Running both systems against the same mailbox causes customers to receive two answers and agents to work the same ticket twice. Pick one system as the sole sender for each mailbox, disable auto-replies and macros in the retiring tool, and log every cutover step with its timestamp.

Rate-limit stalls during API pulls

Large Inbox API 2.0 pulls can slow or pause when the account hits its rate limits, which makes a long export look stuck. Schedule pulls in batches with checkpoints, record the last conversation ID retrieved, and resume from it rather than restarting. Check the current limits in the Help Scout API documentation before you size the batches.

Missing saved replies and modules

Saved replies are not carried over automatically, and FreeScout modules such as SAML SSO, LDAP or Knowledge Base are licensed per instance, so a lapsed license or update can disable a feature agents depend on. Rebuild saved replies from an export, confirm each required module is licensed for the production instance, and verify that the license renewal date is on the owner's calendar.

How the migration differs by team size and starting point

A small team with one shared inbox usually has the narrowest migration. The main question is how much history must move and whether the team can accept a short period where new email arrives in one place while older threads sit in another. Because FreeScout's README lists unlimited agents, tickets and mailboxes, the license side is simple, and the work concentrates on mail routing, the saved replies people actually use and a clean cutover of the inbox address.

Scope: Decide whether to pull the full conversation history through the Help Scout Inbox API 2.0 or to archive older threads and import only recent ones.
Sequence: Stand up FreeScout, connect the mailbox over IMAP or SMTP, then change forwarding or DNS for the support address at a planned point.
Saved replies: Recreate the handful of templates that agents use daily instead of migrating every legacy snippet.
Validation: Send test messages in both directions and confirm replies thread correctly under the original customer.
Plan constraints: Confirm which Help Scout plan features and exports apply to your account before you start, since rate limits and export options depend on it.

Before cutover, check that a sample of migrated conversations opens with attachments and that the team knows where to answer old threads during the overlap period.

Questions buyers ask before moving from Help Scout to FreeScout

What drives the cost of moving from Help Scout to FreeScout?

FreeScout's software has no license fee because it is licensed under AGPL-3.0, so your costs come from hosting, email setup, paid modules and migration work. Hosting and mail delivery recur every month, and someone must apply updates, since FreeScout publishes releases roughly weekly. Modules such as LDAP Integration, SAML SSO, Knowledge Base, API and Webhooks, Satisfaction Ratings, Time Tracking and Workflows are sold as lifetime licenses for a single instance, with lifetime updates, according to the FreeScout modules page. AI Integration and S3 Storage are listed as free. Migration is usually the largest one-time item. Ask for a quote that lists each module, the hosting model, the mailbox count, the data volume and what the migration includes.

How long does a Help Scout to FreeScout migration take?

The timeline depends on scope, and no general duration is supplied here, so confirm it against a written plan. The main drivers are conversation and attachment volume, the number of mailboxes and how their email is routed, how many saved replies and workflows must be rebuilt, which modules are needed on day one, and how much testing agents need before cutover. Email routing is often the slowest step, because DNS or forwarding changes take time to propagate and mail flow must be checked from both sides. A team with few mailboxes and a modest history will move faster than one with years of attachments across several shared inboxes. Ask for a plan that lists each phase, its dependencies and the acceptance checks agreed in writing before work starts.

What does our internal team need to provide?

Name one owner on each side and plan for each role to give time at the key points, although the exact effort depends on your environment. A Help Scout administrator needs to create the OAuth 2 application for the Inbox API and confirm what is exported. A domain administrator controls DNS and mail forwarding. A mail administrator supplies the SMTP and IMAP details for each mailbox. A support lead maps teams, folders, tags and saved replies, and a few agents test replies, attachments and notifications. Someone must also decide which modules to buy and keep the license records. Keep the final decisions with the people who approve the scope, and confirm the exact access each step needs with the vendors involved.

Can our own team migrate from Help Scout in-house?

A capable internal team can do it, particularly for a small shared inbox, but the work includes several specialized steps. An API import requires someone comfortable with OAuth 2, paging through the Inbox API 2.0, mapping customers and threads, and handling attachments within the rate limits of your Help Scout plan, which you should confirm. FreeScout's migration service is an alternative path for moving from other help desks, so check whether it fits your source. Mail routing, module configuration and server hardening also need skills your team may or may not hold. If you proceed in-house, write down the mapping rules and run a test import into a staging instance first. DeployOpen plans, implements, integrates, backs up and documents self-hosted platforms in your own infrastructure under a fixed-scope written agreement, so you can ask for that scope as an alternative.

Do conversations, attachments and customers move to FreeScout?

Conversations, threads, attachments and customers can be pulled from Help Scout through its Inbox API 2.0, which uses OAuth 2, and imported into FreeScout by a script or through FreeScout's migration service. Before you start, confirm which object types each path carries across, how attachments are stored, and whether timestamps, assignees and tags keep their values. Confirm the Help Scout rate limits for your plan too, because large histories are pulled in batches and take longer. After the import, compare record counts, sample threads from several years, check that attachments open correctly, and confirm that customer records were matched without creating duplicates. Keep the Help Scout export as an archive until the team signs off on the results.

What happens to Help Scout Docs after we move?

Help Scout Docs is a separate product from the shared inbox, so moving the inbox does not move your articles automatically. Your options include FreeScout's Knowledge Base module, which is a paid lifetime license, Chatwoot's Help Center portal, or a standalone BookStack site. Most of these paths change article URLs, so inventory every article link, saved reply and support widget reference before cutover. Export or copy the articles and collections, rebuild the structure, and set up redirects wherever the new addresses differ from the old ones. Confirm the export options for Docs directly with Help Scout, since this page does not cover them, and agree the content plan in your written scope.

Does SSO for FreeScout require a paid module?

Single sign-on for agents depends on the protocol. SAML SSO and LDAP Integration are listed as paid FreeScout modules, so you need a module license for those methods. Microsoft 365 and Google Workspace OAuth for mailbox connections is part of the core software, according to the FreeScout README, so mailbox authentication does not depend on a module. Check that your identity provider supports the protocol the module uses, and confirm whether the license covers future updates for your instance. Decide whether a small number of local break-glass accounts will remain, and document who controls them. Confirm current module terms on the modules page before purchase, because pricing and terms can change.

How are the parallel run and cutover handled?

Most cutovers run the old and new systems side by side for a defined period, with a written rollback plan. A common approach is to set up FreeScout on a test or secondary mailbox, forward a copy of incoming mail, and have agents work a limited set of conversations in the new instance before the primary address moves. Keep Help Scout readable during the overlap so agents can check history. Change MX or forwarding records in a planned window, then monitor delivery, bounces and duplicate notifications. Define in advance who can trigger a rollback, what conditions trigger it, and how replies sent during the overlap are reconciled. Agree the overlap length in your written scope rather than assuming one.

How DeployOpen scopes, runs and supports a FreeScout migration

DeployOpen plans and runs the move from Help Scout to a FreeScout instance inside your own infrastructure, from mailboxes and saved replies through to conversation history and attachments. Each engagement starts with a written scope that names the data, modules and cutover steps before any work begins.

How we scope

Inventory every Help Scout mailbox, shared inbox, saved reply and workflow that agents rely on daily
Agree in writing which conversations, threads, attachments and customers move, and for what date range
Confirm which FreeScout modules are needed for parity, such as SAML SSO, LDAP, Knowledge Base or API access

How we build

Deploy FreeScout on your own servers or cloud accounts with the database and mail configuration you choose
Pull data through the Help Scout Inbox API 2.0 or FreeScout's migration service, then test a sample import
Re-create mailboxes, email routing and saved replies, and check that conversation threads and attachments render correctly

How we hand over

Document the deployment, mailbox configuration, module list and the import steps used for your data
Provide a cutover checklist covering DNS, mail forwarding and the period when both systems run side by side
Walk your administrators through daily tasks such as adding agents, updating modules and managing backups

How we support

Offer ongoing support, upgrades and testing as a retainer after the fixed-scope migration is delivered
Apply FreeScout releases in a staging copy first so mailbox behavior is checked before production changes
Ask your team to confirm which post-migration issues fall under the retainer and which fall under a new scope

Migrate from Help Scout to FreeScout