Migrate from Zendesk to FreeScout

Migrate from Zendesk to FreeScout when email is the core of support

For a small team that uses Zendesk mainly as a shared email inbox, the move is mostly mailbox and ticket history work, not a rebuild. The effort depends on three things: whether you have export access to your Zendesk account, how far back the conversation history goes, and how many Zendesk features your agents use every day. A team that only routes mail, replies and closes tickets has a much smaller job than one that relies on macros, triggers, views and custom fields. Before you weigh the renewal against the cost of moving, confirm which of these apply to your account, because they set the scope more than the ticket count does.

Plan on an internal administrator owning the project, with an implementation partner if the team lacks time or experience with IMAP, SMTP and mail routing. The admin decides how Zendesk data is exported, whether the history is imported through the FreeScout migration service linked from its README or a scripted import through the FreeScout API, and how each shared mailbox is configured. Check the exact export options and plan limits with Zendesk, since exports are not enabled on every plan and may need to be requested from Zendesk support. Confirm the FreeScout migration service's current scope and terms with the FreeScout project before you rely on it.

The main risk is losing conversation history or mail routing at cutover. Keep the Zendesk export as a read-only archive, and test a complete mailbox end to end on a staging FreeScout instance before changing the MX record or forwarding rules for the live address. Replies sent during the switch can land in the wrong system, so agree a freeze window with the team and confirm that customer replies to old threads still attach to the right conversation. Ask the partner, in writing, how they will verify message counts and attachments after import and how they will roll back if routing fails.

Which Zendesk capabilities map cleanly to FreeScout

This table compares the Zendesk capabilities that small support teams usually rely on with what FreeScout includes in its base product and which features sit in paid lifetime modules. Read each status as a planning signal: clean means the base product covers the need, needs rework means a paid module or a configuration step is involved, and gap means you must confirm the capability before you commit to the migration.

Capability	FreeScout coverage	Status
Shared inbox and email routing	Unlimited mailboxes with email over SMTP, IMAP and POP3, plus collision detection to flag two agents replying to one conversation	Clean
Users and agents	Unlimited agents are included, but the README does not describe a bulk user import, so confirm how your Zendesk users will be created	Needs rework
Mailbox connections	OAuth authentication for Microsoft 365 and Google Workspace, with IMAP and SMTP for other providers	Clean
Knowledge base	Available only through the paid Knowledge Base module, a lifetime license for one instance	Needs rework
Satisfaction ratings	Available only through the paid Satisfaction Ratings module, a lifetime license for one instance	Needs rework
Automation, triggers and macros	Workflows is a paid lifetime module, and the API, Webhooks, Zapier and Make cover some integration needs. Confirm each Zendesk trigger and macro against your configuration	Needs rework
SSO and LDAP	LDAP Integration and SAML SSO are paid lifetime modules, so budget for them if your agents sign in through a directory	Needs rework
Reporting	Not described in the README or modules page. Confirm the reports your team uses in Zendesk exist in FreeScout before migrating	Gap until confirmed
Mobile access	Android and iOS apps offer the same functionality and modules as the web version, and the web app works as a progressive web app	Clean

What to export from Zendesk and what to rebuild

Moving a shared inbox from Zendesk to FreeScout is mostly a data question and a routing question. The export paths Zendesk documents decide what history you can keep, and the mail routing that Zendesk handled for you must be recreated on the FreeScout side before cutover.

Confirm your Zendesk export tier

Zendesk offers JSON, CSV and XML exports on Suite Growth and higher and on Support Professional and higher, not on Team plans. Exports are not enabled by default, so the account owner must ask Zendesk support to switch them on. Ask for this early, because the request is outside your own admin settings and can delay the whole project. If your plan is below these tiers, confirm with Zendesk what export options exist before you plan the migration.

Choose JSON over CSV for ticket history

The CSV export omits ticket comments and descriptions, so a CSV-only copy loses the conversation a shared inbox depends on. XML exports are capped at 500 MB and are unavailable above 200,000 tickets. Zendesk recommends JSON for accounts above that ticket count, so pick the format by account size before you request the export.

Map users and mailbox addresses

Export the users and organizations along with tickets, then list every address that receives mail for the shared inbox, such as support, billing and sales aliases. FreeScout needs each mailbox defined with its own IMAP and SMTP settings, and agents need accounts with the right access to each mailbox. Check which requesters already exist as customers so you do not create duplicate contacts when conversations are imported.

Rebuild forwarding and routing rules

Zendesk triggers, automations and forwarding addresses decide who sees a message and when it is escalated. None of these move through a data export, so write each rule down from the Zendesk admin screens before you change DNS or mail forwarding. Then recreate the equivalent routing in FreeScout, and test with sample messages that each mailbox delivers to the right agents.

Check integrations and attachments

Review every app connected to Zendesk, such as chat widgets, CRM sync and webhooks, and decide whether each one still needs to exist after cutover. Attachments are a separate check, because they must be retrieved with the ticket data and confirmed in FreeScout after import. Keep a complete JSON export on file so that any integration gap can be investigated against the original records.

Pick an import path

The FreeScout README links two import routes: its migration service for moving data from other help desks, and the FreeScout API for a scripted import of your own export. The migration service suits a one-time move with limited customization, while a scripted import gives you control over mapping but needs developer time to build and test. Ask each option what it maps, how it handles attachments and whether it can be rerun.

How the FreeScout migration sequence runs, step by step

The sequence moves a shared Zendesk inbox into FreeScout in controlled stages, so each mailbox is proven on a pilot before the team relies on it, and Zendesk is retired only after a retained export exists.

Inventory mailboxes, agents and open conversations
Before touching any data, list every support address that feeds Zendesk, every agent who works those queues, and every open or pending ticket with its assignee. Include auto-forwarding rules, macros and any integrations that send mail or create tickets. Owners are the support lead and the Zendesk account owner. The output is a written inventory that names each mailbox, its current forwarding path and the people who must be able to log in to FreeScout on day one.
Export and validate Zendesk data
Request the account export from Zendesk. On Support Professional and higher, or Suite Growth and higher, the account owner must first ask Zendesk support to turn exports on, and Team plans do not offer them. Choose JSON if the account holds more than 200,000 tickets, because the CSV export omits comments and descriptions. Store the export in a location outside Zendesk and check ticket and user counts against the inventory. The output is a verified, retained copy of the data.
Choose the FreeScout migration path
Decide between the migration service linked from the FreeScout README and a scripted import through the FreeScout API. The service suits teams that want the vendor path and can confirm its scope in writing. A script suits teams with in-house developers who need control over field mapping, attachment handling and user matching. Either way, confirm with the chosen provider which Zendesk data types are covered before work starts. The output is a documented decision with its scope.
Set up mailboxes over IMAP and SMTP
Install FreeScout on your own server using the Docker image or a supported install method, then create one mailbox per support address. Configure inbound mail over IMAP and outbound mail over SMTP for each. For Microsoft 365 or Google Workspace mailboxes, use the OAuth option instead of stored passwords where your tenant policy allows it. Send a test message in and out of every mailbox. The output is a set of mailboxes that send and receive mail without errors.
Run a pilot mailbox
Import one low-risk mailbox and its related conversations into FreeScout, then have a small group of agents work them for a set period you agree internally. Check that threads, attachments, customer records and assignees match the Zendesk export. Record every mismatch and fix the mapping before the next import. The output is a signed-off pilot report that the support lead accepts.
Parallel run with forwarding
Migrate the remaining mailboxes and keep Zendesk receiving mail while FreeScout receives copies through forwarding rules. Agents work new mail in FreeScout and check Zendesk only for history. Compare daily ticket counts between the two systems to confirm nothing is dropped. Confirm that replies sent from FreeScout reach customers with the correct sender address. The output is a period with no missing messages across both systems.
Cut over MX or forwarding rules
Change the MX record or the forwarding rule so that all inbound support mail goes to FreeScout directly. Do this during a window the support lead chooses, and keep the Zendesk routing in place until the new path is confirmed. Verify SPF, DKIM and DMARC alignment for the sending domain. The output is a confirmed production path in which FreeScout is the only system receiving new support mail.
Decommission Zendesk after a retained export
Close Zendesk only after the retained export has been checked, the open tickets are closed or moved, and the agreed review period has passed without issues. Ask Zendesk how long data remains available after cancellation and confirm the deletion terms in writing. Keep the export under your own retention policy. The output is a closed Zendesk account and a documented archive that your compliance team can locate.

Migration service or scripted API import: how to choose

Choose the import path after you have confirmed what each one moves, because the two options differ mainly in control and in who does the work. The FreeScout README links a migration service for moving in from other help desks, and a scripted import uses the FreeScout API, which the same README links. The service may save scripting time, but the supplied material does not describe its exact scope, so ask the provider in writing which Zendesk objects it maps (tickets, threads, users, organizations, tags, statuses, attachments and agent assignments), how it handles Zendesk comments that the CSV export omits, what it does with closed tickets, and what happens to data that does not map cleanly. Treat the answers as part of the scope you agree before any data moves.

A scripted API import gives you control over each mapping decision. You decide how Zendesk users become FreeScout users, how Zendesk statuses map to FreeScout conversation states, and whether attachments are re-uploaded or skipped. The trade-off is developer time: someone must write the extraction logic against the Zendesk export, handle pagination and failures, and test edge cases such as duplicate requesters and large attachments. Confirm the FreeScout API endpoints and their permissions in the version you run, since the API is a module feature that is only available with a paid license, and check that the mailbox routing you need is covered before you commit to a design.

Test both paths against a copy of the data, not the production inbox. Load the same sample of tickets through each option into a separate FreeScout instance, then compare ticket counts, requester addresses, timestamps, agent assignments and attachment links. Keep the Zendesk export as the authoritative backup, retained under your own retention policy, so any gap found after cutover can be traced back to source. Record which option produced fewer manual corrections, and let that result, not the sales pitch, decide the path.

What usually goes wrong and how to prevent it

Most failed Zendesk-to-FreeScout moves fail on data, not software. The risks below cluster around the export, the comment history, the mail flow during parallel running, attachments and threads, and the modules a team buys before it knows what it needs.

Incomplete export from Zendesk

Zendesk does not enable JSON, CSV and XML exports by default, and only Suite Growth and higher and Support Professional and higher include them. A team on a Team plan, or one that never asked support to switch exports on, can discover this after the cancellation date. Before anything else, confirm the plan, ask the account owner to request the export from Zendesk support, and check that the file contains every ticket and user you expect.

CSV export drops comments

The CSV export leaves out ticket comments and descriptions, so a team that uses it alone loses the conversation history that makes an old ticket useful. Keep the JSON export as the complete copy, and treat CSV only as a readable index. For a shared inbox, a quick spot check on three or four long threads after import shows whether the replies arrived.

Mail routing errors during parallel running

While both systems are live, a customer reply may land in Zendesk while the agent works in FreeScout, or both systems may send an acknowledgement for the same message. Set a dated freeze in which Zendesk stops accepting new mail, then move each mailbox's forwarding in one step. Use a test mailbox to send a message through IMAP and SMTP, confirm that exactly one ticket and one reply appear, and only then switch the public address.

Lost attachments and broken threads

Imported tickets can lose attachments if the export references files that the importer does not fetch, and replies can open as separate conversations if message IDs or subjects do not match. Ask the vendor or the FreeScout migration service how attachments are handled, then import a sample ticket that has a large attachment and a multi-reply thread. Confirm both before running the full import.

Modules bought before the need is confirmed

FreeScout's paid modules, such as Knowledge Base, SAML SSO, LDAP, Workflows and Satisfaction Ratings, are sold as lifetime licenses for one instance. Buying them before the team lists which Zendesk features it actually used adds cost that can be avoided. Write down the features used in the last three months, map each to a module or a built-in function, and buy only what remains on that list.

How the migration changes by team size and starting point

A team with one or two mailboxes and a short history usually has the simplest path. Most of the effort goes into mailbox setup, and the history question is a judgment call: carry over the threads agents still act on and keep the rest in a searchable archive.

Set up mailboxes first. Create the FreeScout mailboxes over IMAP and SMTP and point the support addresses at them, so new mail lands in FreeScout from the first day of cutover.
Import only open and recent threads. Older closed conversations rarely justify a scripted load. Keep them in an export you can search.
Check whether the migration service fits. The FreeScout README links a migration service for moving in from other help desks. Ask the provider what it covers for a Zendesk source, how it handles attachments, and how long it takes.
Keep a manual copy. Whatever you do not import should still be exported and stored, so the record survives once the Zendesk subscription ends.

Before choosing between the service and a scripted import, confirm which export options your current Zendesk plan includes and get the migration service's scope in writing.

Questions buyers ask before moving from Zendesk to FreeScout

How much does a move from Zendesk to FreeScout cost?

The cost depends on the drivers that shape the work: the size of the ticket history, how many mailboxes need reconnecting, which paid FreeScout modules the team wants, and which integrations must be rebuilt. FreeScout's core is free under AGPL-3.0, so the main costs are hosting, the one-time migration work, any module licenses, and internal admin time. Module licenses are sold as lifetime licenses for a single FreeScout instance on the FreeScout modules page, so check which modules you need before you buy. Ask any vendor or partner for a written quote that lists each component separately: export and import scripting, mailbox configuration, module purchases, hosting setup, and testing.

How long does a Zendesk to FreeScout migration take?

The timeline is set by the sequence of work more than by the tool itself. A typical path runs through export, import into a test instance, validation of tickets, users and attachments against the source, mailbox cutover, and then a short parallel run before Zendesk is closed. Export validation is the step teams most often underestimate, because a ticket count that matches does not prove that comments, attachments and requester details arrived intact. Ask for a written schedule with a named validation step and a test window agreed in advance.

Can our team do the migration alone, and what does it need?

A small team can often run it alone if it has the right access and time. You need a Zendesk administrator who can request exports, a person who can build or run the import through the FreeScout API or the FreeScout migration service, and a mail administrator who can configure IMAP and SMTP for each shared mailbox and set up DNS and SPF records for outbound mail. You also need a test window where the old and new inboxes can be compared without losing incoming email. If any of these roles is missing, the gap is usually mail configuration or import scripting, and that is where outside help tends to be used.

Do Zendesk exports include ticket comments?

It depends on the export format. Zendesk's CSV export omits ticket comments and descriptions, so a CSV-only export will lose the conversation history that matters most in a shared inbox. JSON and XML exports are available on Suite Growth and higher and Support Professional and higher, not on Team plans, and the account owner must ask Zendesk support to turn exports on because they are not enabled by default. XML exports are capped at 500 MB and are unavailable above 200,000 tickets, and Zendesk recommends JSON for accounts with more than 200,000 tickets. Confirm your plan tier and ticket count before you plan the export.

Does FreeScout have a licensing limit on agents and mailboxes?

The FreeScout README lists unlimited agents, tickets and mailboxes for the core application, which is licensed under AGPL-3.0. That means the base help desk does not charge per agent or per mailbox. Paid modules are a separate matter: they are lifetime licenses for a single FreeScout instance, and some features such as LDAP, SAML SSO, knowledge base, workflows and satisfaction ratings sit in those modules. Because AGPL-3.0 has source disclosure obligations when you modify and offer the software over a network, have your legal or licensing team review any custom changes before you deploy them.

What should we ask for in a written quote?

Ask for a fixed scope that lists each deliverable and its acceptance test. Useful items to request include:

Export plan: which Zendesk export format is used, who requests it, and how completeness is checked against ticket counts and attachments.
Import method: whether the work uses the migration service linked from the FreeScout README or a scripted import through the FreeScout API, and how errors are logged and retried.
Mailbox setup: IMAP, SMTP and OAuth configuration for each shared mailbox, plus DNS records.
Module list: which paid modules are included, with license terms and who purchases them.
Testing, cutover, rollback, and a named post-cutover support period.
Hosting and backup responsibilities, and what is excluded from the fixed price.

What breaks most often in a FreeScout mailbox cutover?

Most problems happen at the mail layer rather than in the ticket data. Common issues include IMAP credentials that stop working when a provider changes authentication, missing SPF or DKIM records that cause outbound replies to land in spam, and forwarding rules in Zendesk that still send mail to the old address after cutover. Plan a short period in which both systems receive mail, confirm that every shared mailbox is polling correctly, and check that replies carry the right sender address. Confirm the supported authentication method for your mail provider, including OAuth for Microsoft 365 and Google Workspace, before the cutover date.

Keeping a Zendesk export as the record after shutdown

Keep a full Zendesk export as the retained record before the account closes, because the import into FreeScout will not carry every field, attachment and event forward in a form an auditor would accept as complete. The JSON export is the copy to keep. Zendesk offers JSON, CSV and XML exports on Suite Growth and higher and Support Professional and higher, not on Team plans, and the account owner must ask Zendesk support to turn exports on because they are not enabled by default. Confirm your plan and request the export while the account is still active, since the owner's request is the step most likely to delay the work.

The CSV export is not enough for a record. Zendesk's CSV export omits ticket comments and descriptions, which are the substance of a support conversation. XML exports are capped at 500 MB and are unavailable above 200,000 tickets, and Zendesk recommends JSON for accounts with more than 200,000 tickets. Check the size and ticket count of your account against those limits, then store the JSON files in a location your organization controls, with a checksum and a note of the export date and the account owner who requested it. Test that the files open and that comments appear before you rely on them.

Confirm retention obligations with your compliance owner before you decide how long the export is kept, where it is stored and who may read it. Retention periods, legal holds and personal data rules for customer correspondence vary by sector and jurisdiction, and this page does not set them. Ask the compliance owner which records must be kept, for how long, and whether the export counts as the system of record or only as a backup. Those answers decide whether the FreeScout mailboxes or the archived export serve as the reference for later requests.

How DeployOpen scopes and runs a FreeScout migration

DeployOpen plans, implements, integrates, hardens, backs up and documents self-hosted open-source platforms inside your own infrastructure, so a move from Zendesk to FreeScout is handled as a defined engagement with written deliverables. The work covers the export, the import path, mailbox configuration and handover, with support available afterward.

How we scope

Inventory which Zendesk mailboxes, views, macros and triggers the team relies on before choosing an import path.
Confirm the Zendesk plan and whether the account owner can enable exports, since that affects what data can be pulled.
Agree in writing which modules are in scope, such as Knowledge Base or Workflows, and which are deliberately left out.

How we build

Set up the FreeScout instance on your own servers with PHP, a supported database and Nginx or Apache, following your hosting standards.
Configure each shared mailbox over IMAP and SMTP, or OAuth for Microsoft 365 or Google Workspace, and test inbound and outbound mail.
Run a trial import of a sample of tickets and users through the migration service or a scripted API import, then check threads, attachments and agent assignments.

How we hand over

Document the mailbox settings, module licenses, user roles and the import procedure so the team can repeat or audit it.
Deliver a cutover checklist covering DNS or forwarding changes, a freeze window for new Zendesk tickets and a rollback path.
Keep a retained archive of the final Zendesk JSON or CSV export so historical records remain available after Zendesk access ends.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer after handover, covering FreeScout release updates.
Confirm with your team how backups of the FreeScout database and attachment storage will run and be restore-tested.
Ask for a fixed-scope quote based on the written scope, since no published price list applies to this engagement.

Migrate from Zendesk to FreeScout