How to migrate from Zendesk to Zammad
Move Zendesk to self-hosted Zammad: secure the API token the import needs, time a test run, rebuild the rules, then import once and switch the mail.
In short
- Zammad’s migrator brings across groups, organisations, users, custom fields and tickets with comments, attachments and tags; triggers, automations, macros, views, SLAs and Help Center articles are rebuilt.
- The migrator signs in with a Zendesk API token; Zendesk stopped issuing new tokens on 27 October 2026 and switches all of them off on 30 April 2027.
- The import runs once into a fresh instance with no delta pass, so a timed test run sizes the window and tickets that arrive during it are finished in Zendesk.
- Each ticket’s comments are fetched with requests of their own, so the import’s pace is set by the Zendesk plan’s per-minute API limit, shared with every other integration.
On this page (14)
Moving from Zendesk to Zammad is an import with a rebuild around it. Zammad’s built-in Zendesk migrator reads your account through the Zendesk API and brings across groups, organisations, users, custom fields and tickets with their comments, attachments and tags. Triggers, automations, macros, views, SLA policies and the Help Center stay behind and are rebuilt by hand. The migrator runs once, into a fresh instance, with no delta pass, so the cutover is planned around a timed test run. And because Zendesk is retiring API tokens, the work now starts with the one credential the migrator needs. This guide covers the order we run it in, and the places it usually goes wrong.
Why teams move from Zendesk to Zammad
Three reasons come up again and again.
- Customer conversations in your own database. Tickets carry names, contracts, complaints and the attachments people send with them. With Zammad on your own machines, they sit in PostgreSQL and an attachment store, in the location you choose.
- One edition, no feature tiers. In Zendesk, account data exports, custom agent roles and the API rate limit depend on the plan. Zammad ships as one edition: every channel and feature, SAML, OpenID Connect and LDAP sign-in included, is in the self-hosted code.
- Reachable only on your network. Agents work in Zammad over a private network. Only what customers and messaging services have to reach, such as the web form, the chat and the WhatsApp and Telegram webhooks, is published.
What you give up is real: the Zendesk Marketplace, Zendesk Talk as a built-in phone system, satisfaction ratings and side conversations, which have no built-in counterpart in Zammad, and the fact that Zendesk runs the platform. Zammad takes call events from your phone system through CTI integrations, but it is not a phone system itself.
Step 1: secure API access and take an export
Zammad’s migrator asks for your Zendesk URL, the email address of a full administrator and a Zendesk API token. Zammad’s Zendesk migration guide warns that a token from a less privileged account ends in a broken migration.
The token is now the hard part. Zendesk is removing API tokens as an authentication method:
- From 28 July 2026, a token unused for 30 days is deactivated, and deleted 60 days later unless an admin reactivates it. Accounts created on or after that date cannot use tokens at all.
- From 27 October 2026, nobody can create a new token. Existing active tokens keep working.
- On 30 April 2027, every remaining token stops working for good.
As of 14 November 2026, Zammad’s migrator takes a token and nothing else: support for Zendesk’s OAuth clients is an open request in Zammad’s issue tracker. So check first:
- Find a usable token. In Admin Center, open Apps and integrations, APIs, API tokens. An active token works, and so does a deactivated one still inside its 60 days, once reactivated. A token is not tied to a user, so it works with any full administrator’s email address.
- Keep it alive. Use it at least once every 30 days between the test import and the final one.
- Finish before 30 April 2027. The final import has to run while the token works.
With no token left, the migrator cannot connect until Zammad supports OAuth. The alternatives are to wait, or to write an import of your own that reads Zendesk’s API through an OAuth client and writes to Zammad’s REST API, the route Zammad’s documentation gives for sources it has no migrator for. That is a development project in its own right.
Take an export of your own as well. The import is not a backup of Zendesk, and Zendesk’s account data export does not use API tokens.
| Zendesk export | What it holds | Limits |
|---|---|---|
| Full JSON export | Tickets with comments, users or organisations, one per line | The one Zendesk recommends for large accounts; very large tickets lose their comments |
| CSV export | Ticket fields and metrics such as reply and resolution times | No comments, descriptions or deleted tickets |
| XML export | All ticket data, or user data on its own | Not offered above a ticket count Zendesk sets; no custom user or organisation fields |
Zendesk’s export article gives the current size limits. Exports run from Admin Center, Account, Tools, Reports, on Suite Growth and above or Support Professional and above; Team plans have the API only. Data exports are off by default and the account owner asks Zendesk Customer Support to enable them, so make that request on the first day.
Step 2: inventory the rules, channels and Help Center
The migrator moves the data, not what Zendesk does with it. List each of these with an owner:
- Business rules. Triggers, automations and SLA policies under Objects and rules, Business rules in Admin Center, plus macros and views. The API returns each set as JSON (
/api/v2/triggers,/api/v2/automations,/api/v2/macros,/api/v2/views,/api/v2/slas/policies,/api/v2/business_hours/schedules): the specification you rebuild from. - Email addresses. Each support address, its mailbox, the forwarding rule that sends its mail to Zendesk, and the SPF and DKIM records that let Zendesk send as your domain.
- Web channels. Every site that loads the Zendesk Web Widget or messaging, and the Help Center request form.
- The Help Center. Categories, sections and articles in each language, and the domain it answers on.
- Integrations. Marketplace apps, webhooks and every system that calls the Zendesk API.
Zammad’s documentation also says objects with Cyrillic strings cannot be migrated, so rename those groups, fields and options first. And since the import is all or nothing, clean up what you do not want in Zammad before the final run.
What the Zendesk migrator brings across
Imported
- Groups, with each agent’s memberships
- Organisations and users, with their custom fields
- Custom ticket fields of the types it supports
- Tickets, keeping their Zendesk numbers
- Public comments and internal notes, with their timestamps
- Attachments, inline images and tags
Rebuilt or left behind
- Triggers, automations, macros and views
- SLA policies and business hours
- Help Center articles
- Satisfaction ratings and side conversations
- Passwords
- Email addresses, widgets and integrations
Step 3: run a test import and time it
Build a scratch instance the way production will be built, with PostgreSQL, Elasticsearch and attachments in the filesystem store, and run the migrator against the live account. It only reads from Zendesk, so agents keep working.
A fresh Zammad instance offers the import in its setup wizard. For large accounts Zammad recommends the console instead (zammad run rails c on a package install, docker compose run --rm zammad-railsserver bundle exec rails c with Docker):
Setting.set('import_zendesk_endpoint', 'https://acme.zendesk.com/api/v2')
Setting.set('import_zendesk_endpoint_username', 'admin@acme.example')
Setting.set('import_zendesk_endpoint_key', '<api-token>')
Setting.set('import_backend', 'zendesk')
Setting.set('import_mode', true)
# Test the connection without importing anything
Sequencer.process('Import::Zendesk::ConnectionTest')
# Start the import; it is still running while finished_at is nil
job = ImportJob.create(name: 'Import::Zendesk')
AsyncImportJob.perform_later(job)
pp ImportJob.find_by(name: 'Import::Zendesk')
After a console import, Zammad’s guide has you set import_mode to false and system_init_done to true, clear the cache with Rails.cache.clear, then set the FQDN and HTTP type in the system settings, which the skipped setup wizard would have asked for.
What sets the pace
The migrator lists organisations, users and tickets through Zendesk’s incremental export, which returns records in large pages under a tighter rate limit of its own. It then fetches each ticket’s comments with requests of their own, which count against the per-minute limit of your Zendesk plan. Zendesk’s rate limits page gives the figures for each plan, and for the High Volume API add-on, which raises the limit from Suite Growth or Support Professional upwards with a minimum number of agent seats.
The limit is the account’s, so every integration calling the Zendesk API during the import draws on it; the migrator waits and retries when it hits the limit. Time the test run and size the final window from it.
Check what arrived
- Counts. The import job reports created, skipped and failed records per object; compare them with Zendesk. Deleted tickets are skipped by design, while closed and archived ones come across.
- Fields. Field types the migrator does not support, such as lookup relationship fields, are skipped and logged.
- Roles. End users arrive as customers, admins as admins and agents as agents, but an agent with unrestricted access in Zendesk also receives Zammad’s Admin role. Review roles before anyone signs in.
- States and priorities. Solved tickets arrive closed, on-hold tickets open and pending tickets as pending reminder. Urgent becomes high, the top of Zammad’s three default priorities.
- Threads. The leads of the busiest groups open a sample of tickets and check comments, notes, attachments and inline images. An attachment that still fails after the migrator’s retries is skipped and logged.
To run the test again, reset the instance with the commands in Zammad’s documentation, or build a new one: Zammad imports only into a new instance, from one source.
Step 4: rebuild the rules and the knowledge base
Everything in this step is built in staging, signed off by the team leads, and built again on production after the final import.
| Zendesk | Zammad |
|---|---|
| Groups | Groups, with read, create, change, overview or full access per agent |
| Admin, agent and custom roles | Admin, Agent and Customer roles, plus roles of your own |
| Ticket fields and ticket forms | Object attributes, shown or hidden per condition with core workflows |
| Triggers | Triggers |
| Automations | Scheduler jobs, which process a capped number of objects per run |
| Macros | Macros for field changes and notes, text modules for reply text |
| Views | Overviews, best kept few, each showing a capped number of tickets |
| SLA policies and business hours | SLAs, with business hours and holidays in calendars |
| Help Center | Knowledge base |
| Zendesk Talk | CTI integration with your phone system |
Macros split in two. A Zendesk macro often sets fields and writes the public reply in one click. A Zammad macro changes ticket attributes, adds notes and sends notifications, but has no action that replies to the customer. Rebuild the field changes as a macro and the reply as a text module, which agents insert while they write. Both can be limited to the groups that use them.
SLAs need a calendar first. Set business hours and holidays in a calendar, then create SLAs against it. A ticket escalates when a deadline passes, and triggers or scheduler jobs act on escalated tickets.
The Help Center becomes the knowledge base. Articles come out of Zendesk’s Help Center API (/api/v2/help_center/articles, with categories and sections) and go into Zammad’s knowledge base API as categories and answers. Categories nest, so a Zendesk category and its sections become a category with sub-categories. Each answer is a draft, staff-only or public, in as many languages as you publish. The knowledge base answers at /help on the Zammad host, or at a custom URL on a self-hosted instance. If your Help Center ran on your own domain, point it at the knowledge base and redirect the old article addresses, so links in old emails and search results keep working.
Replaying on production. Zammad’s REST API has endpoints for triggers, scheduler jobs, macros, text modules, overviews, SLAs, calendars and knowledge base content, so a script can replay those after the final import; have it find groups and fields by name, not by ID. The rest is re-entered from the signed-off staging setup.
Step 5: connect sign-in
Passwords do not move. The migrator gives the administrator whose email address it used a login with the API token as password: change it at the first sign-in. Everyone else signs in through single sign-on, or sets a password through the reset link on the login page.
Connect the identity provider for agents before go-live, under Settings, Security, Third-party Applications:
- SAML or OpenID Connect. Zammad’s documentation has step-by-step guides for Keycloak and Microsoft. Its OpenID Connect sign-in needs discovery and HTTPS on both sides, and refuses self-signed certificates.
- Automatic account link on initial logon. Set it to yes. Zammad then matches a sign-in to the imported account by email address; without it, people are told their address is already in use. Pair it with No user creation on logon to refuse anyone without an account.
- LDAP or Active Directory. The sync assigns Zammad roles from directory groups, so a leaver loses access with everyone else.
Customers who used the Zendesk Help Center set a password through the same reset link if they use Zammad’s customer portal.
Step 6: import once, then switch the mail
With no delta pass, the order matters more than the speed.
The cutover, in order
- Freeze: Configuration stops changing in Zendesk: no new groups, fields or forms after the last test import.
- Import: The final import runs into a fresh production instance, in a window sized by the test run, while agents keep answering in Zendesk.
- Rebuild: The signed-off rules, knowledge base and sign-in go onto the new instance, and the counts are checked again.
- Switch: Forwarding to Zendesk stops, Zammad starts reading each support mailbox, and the chat and web form replace Zendesk’s on your sites.
- Finish: Tickets that reached Zendesk after the import are finished there by the agents who hold them.
The mailboxes
Pilae does not operate mail: Zammad reads the mailboxes you already have, over IMAP and SMTP, or through its Microsoft 365 and Google channels with OAuth. Zammad’s documentation warns about two defaults when you add each one:
- It deletes what it fetches. Set Keep messages on server to yes in the expert settings; Zammad then marks fetched messages as read and fetches only unread ones.
- It auto-replies to every message it imports, old ones included. When the mailbox already holds mail, Zammad switches on archive mode, which imports messages older than a cut-off time in a state you choose, usually closed, with their original dates and no auto-reply.
Messages still in a support mailbox were forwarded to Zendesk and are already in the import, so move them out of the folder Zammad reads before connecting it. Then switch one address at a time: connect the mailbox, remove the forwarding rule to Zendesk, send a test message and check the reply leaves from your address. Keep the SPF and DKIM records for Zendesk until its last ticket is finished, because Zendesk still sends those replies.
One detail catches teams out. Zammad recognises a reply by its ticket number in the subject and by message IDs, and an imported comment holds Zendesk’s comment ID, not the Message-ID of the email Zendesk sent. A customer replying to an old Zendesk email may therefore open a new ticket, which agents merge into the imported one: it carries the Zendesk ticket number.
The chat and the web form
Zammad’s chat, under Channels, Chat, is a script on your site, and its widget shows only when an agent is available. The web form, under Channels, Form, takes a name, an email address, a message and an optional attachment, with one form per instance; forms that need more fields go through the customer portal or Zammad’s API. Replace the Zendesk widget on each site in the release that adds Zammad’s.
Step 7: retire Zendesk
- Finish the remaining tickets, then stop working in Zendesk.
- Take a final full JSON export as your record of what Zendesk held on the last day.
- Deactivate the API token in Admin Center.
- Remove the DNS records that let Zendesk send as your domain, and move any domain that pointed at the Help Center.
- End the subscription at the next renewal, once nobody needs to look anything up.
Running Zammad in production
Zammad is several processes around one database.
- PostgreSQL, the only database Zammad supports, for tickets, users and settings.
- Elasticsearch, optional on paper and needed in practice: without it search is slow and attachment contents are not searchable. The index is rebuilt from the database, not backed up.
- Redis and Memcached for the websocket traffic that updates agents’ screens and for the shared cache.
- A watched scheduler. Its background jobs fetch the mail. When it stalls nothing looks broken: new mail stops arriving and the queue looks like a quiet day.
- Backups and upgrades. A backup is a PostgreSQL dump and an archive of the attachment store, restored onto the version it was taken from. Upgrades go one major version at a time, and some ask for a search index rebuild.
Pilae operates Zammad this way, with attachments in the filesystem store from the first day and 60-second probes that read Zammad’s own health check, which reports a stalled scheduler, failed background jobs and any mailbox it cannot reach. The database and attachment store are backed up daily, encrypted, to an offsite location in the country your contract names, and on Enterprise a restore test every month is recorded in the console. The Pilae Agent takes upgrades one major version at a time, each tried on a copy, approved by you and applied in your window. It runs on your premises or on dedicated machines in Pilae Cloud, with agents on your private network and only the web form, chat and messaging webhooks published through its public gate.
Let Pilae run the move
Pilae runs Zendesk to Zammad migrations at a fixed price: the token check and export, the inventory, the timed test import, the rebuild of rules and knowledge base, sign-in, the final import and the switch of every mailbox and widget. Then we operate Zammad for you under a contract that, from the Business plan, includes a monthly availability commitment with service credits. See migration services for what the fixed price covers, or tell us about your Zendesk account and we will scope it.
Questions
Can Zammad import our Zendesk tickets?
Do we still need a Zendesk API token?
Can the import pick up tickets created after it ran?
Do agents keep their Zendesk passwords?
Is Zammad open source?
How long does a Zendesk to Zammad migration take?
Let us run the move for you
An inventory, a parallel run and a cutover plan, at a fixed price. Then we operate the app.
- Go deeperSaaS migrationA fixed-scope migration off Google Workspace, Microsoft 365, Zapier, Airtable and ChatGPT to open-source apps, with a parallel run and a cutover plan.
- CheckManaged operationsPatching, daily encrypted backups, monitoring and incident response for your open-source apps, under an SLA with an availability commitment of up to 99.9%.
