Help Scout to Deskpro migration requires API-to-API extraction — no built-in importer exists. Map Mailboxes to Departments, Conversations to Tickets, and Threads to Messages. Budget 1–4 weeks depending on dataset size.
Migrating from Help Scout to Deskpro requires a fully custom API-to-API ETL pipeline, as Deskpro provides no native Help Scout importer. The fundamental architectural difference is Help Scout's mailbox-centric shared-inbox model versus Deskpro's department-centric ticket model, requiring systematic translation of Conversations to Tickets, Threads to Messages, Customers to People, and Mailboxes to Departments. Help Scout's native CSV export omits message bodies, thread content, and attachments entirely, making direct use of the Help Scout Mailbox API v2 mandatory for any migration that preserves conversation history. Workflows, Saved Replies, and Beacon configurations have no export mechanism and must be fully rebuilt manually in Deskpro.
Read this first
Pair-specific gotchas that catch teams out. Each one has cost somebody a weekend.
TL;DR — Help Scout to Deskpro Migration
A Help Scout to Deskpro migration translates Help Scout's mailbox-centric, shared-inbox architecture into Deskpro's department-centric ticket model. Conversations become Tickets, Threads become Messages, Customers become People, and Mailboxes map to Departments. There is no built-in Help Scout importer in Deskpro — you need a Help Scout Mailbox API v2 → Deskpro REST API v2 pipeline. Help Scout's native CSV export strips message bodies, thread content, and attachments, making API extraction mandatory. Workflows, Saved Replies, and Beacon configurations must be rebuilt manually. Realistic timeline: 1–2 weeks for under 20K conversations; 3–4 weeks for larger datasets with custom fields and knowledge base articles. Verified against Help Scout Mailbox API v2 and Deskpro REST API v2. Rate limit figures are empirically observed; see sourcing notes inline.
Deskpro does not support arbitrary custom ticket statuses
Its status model is deliberately constrained to three core states. If your team relied on Help Scout's pending status in a non-standard way (e.g., as an internal hold state), you'll need to use a Deskpro custom field or workflow state to replicate that behavior.
Cache your token and handle 401 responses by refreshing automatically
Implement 429 handling by honoring the X-RateLimit-Retry-After header. For bulk extraction spanning multiple hours, implement a checkpoint/resume pattern that persists the last successfully processed conversation ID to disk. Token expiry mid-extraction — and the silent data loss it causes when retry logic isn't implemented — is the most common cause of failed DIY migrations.
The List Conversations endpoint returns a preview field containing only a truncated text
The List Conversations endpoint returns a preview field containing only a truncated text snippet of the first message — not the full message body. You must call GET /v2/conversations/{id}/threads for each conversation to retrieve actual content. This is the single most common cause of empty ticket bodies in Help Scout migrations. Skipping the threads call produces tickets with correct metadata and subject lines but zero message content.
Disable outbound email before importing
Under Admin → Emails → Email Settings, disable all outbound triggers before starting the load phase. If you skip this step, Deskpro will send email notifications to every customer whose ticket is created or updated during import — including new-account welcome emails for every Person record created. There is no unsend. Undo means manually contacting affected customers. Re-enable only after QA validation is complete.
Deskpro accepts HTML in message bodies, and Help Scout thread bodies are already HTML
You can pass them through directly — but you must sanitize <img> tags that reference Help Scout's CDN (secure.helpscout.net). Those URLs are authenticated and will return 403 errors after you cancel your Help Scout subscription. See the attachment section below for the correct handling pattern.
Before migration, export every active Help Scout Workflow and Saved Reply to a structured
Before migration, export every active Help Scout Workflow and Saved Reply to a structured spreadsheet: trigger conditions, matching criteria, actions taken, and frequency of use. This document becomes your Deskpro rebuild checklist and also gives you a chance to prune automations that are no longer serving a purpose.
The runbook
Work top to bottom. Tick steps as you go — your progress is saved in this browser.
01 Discovery Establish why you are moving, what "done" means, and who signs off.
Objective A written scope with agreed success criteria, a named owner per workstream, and a budget approved by finance.
Keep these open
-
Pull the real numbers out of Help Scout
Export counts for tickets (open and closed separately), contacts, organisations, attachments, macros, triggers, automations, views and SLA policies. Note the oldest ticket date — history depth drives the whole timeline. Estimating from memory is the single most common cause of a blown migration window.
Data Profiler Get real record counts instead of estimating from memory -
Decide what history actually moves
Agree a cut-off with the support lead: all history, last 24 months, or open tickets plus a read-only archive. Every extra year of closed tickets adds API time and cost without adding much agent value. Get this in writing — it is the decision people relitigate mid-cutover.
A "move everything" default is what turns a two-week migration into a two-month one.
COI & ROI Calculator Build the 36-month business case you will need for sign-off -
Confirm Deskpro can hold your support model
Walk your current workflow through Deskpro: multi-brand, business hours, SLA targets, CSAT, side conversations, public vs internal notes, and any channel you depend on (voice, chat, WhatsApp, social). List anything with no native equivalent — those are project risks, not configuration details.
-
Build the business case
Model licence delta, migration effort, agent retraining, and the cost of staying put (Cost of Inaction). Executives approve a number, not a plan, and you will be asked for it again at the go/no-go.
Helpdesk Migration Planner Turn ticket volume into a dated Help Scout → Deskpro timeline -
Name owners and set the go/no-go date
One named owner each for data, configuration, integrations, and agent enablement, plus a decision-maker who can call a rollback. Put the go/no-go meeting in calendars now, 48 hours before the freeze.
Don't move on until
- Record counts confirmed for tickets, contacts, organisations and macros
- Success criteria signed off by the support lead
- Freeze window provisionally booked with the business
02 Data Audit Find out what is actually in the data before you try to move it.
Objective A profiled, cleaned export with every quality defect either fixed at source or explicitly accepted.
Keep these open
-
Take a full Help Scout export and profile it
Export to CSV or JSON and profile every file: row counts, null rates per column, distinct values, and type consistency. Compare row counts against the API totals from Discovery — a gap here means your export is silently truncated, usually by pagination.
Data Profiler Profile the Help Scout export for nulls, outliers and type drift -
Validate file structure before anyone writes a transform
Check delimiters, quoting, encoding (expect UTF-8, watch for BOMs and Latin-1), duplicate headers, and embedded newlines in ticket bodies. Ticket descriptions with raw newlines and commas break naive CSV parsers and silently shift columns.
A single unescaped quote in one ticket body can shift every subsequent column without any error.
CSV Validator Catch broken headers and ragged rows in the raw export -
Inventory PII and set retention
Scan for emails, phone numbers, payment card fragments, national IDs and anything else regulated in ticket bodies and custom fields — support tickets are where customers paste things they should not. Decide what gets migrated, masked, or dropped, and record the legal basis.
Ticket bodies and attachments routinely contain card and ID data that never appears in a structured field.
PII & Compliance Scanner Find regulated fields before they land in a new system -
Quantify duplicates, orphans and dead references
Count duplicate contacts (same email, different casing), tickets whose requester no longer exists, organisations with no members, and attachments whose parent ticket is gone. Fix these in Help Scout where you can — migrating them just moves the mess.
Data Cleaner Strip empty rows, stray whitespace and dead columns -
Clean and normalise the export
Trim whitespace, drop empty rows and columns, normalise casing on emails and tags, and standardise every timestamp to UTC ISO 8601. Timezone drift is invisible at load time and shows up weeks later as SLA reports nobody can reconcile.
-
Produce a masked copy for sandbox work
Generate a realistic but fake version of the export for testing and for any vendor who needs sample data. Loading real customer PII into a sandbox is a breach in most jurisdictions, and sandboxes are rarely covered by your DPA.
PII Masker Generate a safe copy for sandbox and vendor testing
Help Scout → Deskpro specifics
- Mailboxes
- GET /v2/mailboxes (provides department mapping IDs)
- Customers
- GET /v2/customers (paginated via HAL-style _links.next)
- Conversations
- GET /v2/conversations?status=all&mailbox={id}&sortField=createdAt&sortDirection=asc (include all statuses; use sortField and sortDirection for deterministic ordered extraction)
- Attachments
- Download from thread attachment URLs before Help Scout access expires
- Docs articles
- Docs API v1: GET https://docsapi.helpscout.net/v1/collections/{id}/articles (uses HTTP Basic auth with your API key as the username and "X" as the password — not OAuth)
Don't move on until
- Export parses cleanly with no ragged rows or encoding errors
- PII inventory complete and retention decisions recorded
- Duplicate and orphan records quantified and triaged
03 Field Mapping Turn two schemas into one signed-off mapping spec.
Objective A reviewed field-level mapping covering every object, with an explicit decision for every field that has no target.
Keep these open
-
Generate the first-pass Help Scout → Deskpro field map
Start from an automated match on both schemas, then review every row by hand. Automated matching gets the obvious 70% right and is confidently wrong on the rest — especially anything named "type", "status" or "custom_field_1".
Schema Mapper Opens pre-loaded with the Help Scout → Deskpro field pair -
Map status, priority and channel values, not just field names
Enumerate every value in each picklist on both sides and map them explicitly. Value-level mismatches are the defect class that survives all the way to production because the field itself mapped fine — a ticket that should be "Pending" arriving as "Open" reopens SLA clocks.
Statuses with no target equivalent (on-hold, pending-customer) need a policy decision, not a best guess.
-
Decide how custom fields land
Create the target custom fields first, matching type exactly (a dropdown mapped to free text can never be mapped back). Where Deskpro has no equivalent, decide between a new custom field, a tag, or a note appended to the ticket body — and record which.
-
Resolve identity and threading
Decide how source IDs are preserved — most platforms will not let you set the primary key, so keep the original ID in a custom field. Without it, reconciliation becomes fuzzy matching and every future support question about an old ticket is unanswerable.
Losing the original ticket ID makes reconciliation and rollback effectively impossible.
-
Plan attachments, inline images and threading order
Confirm size limits, allowed MIME types, and whether inline images survive as attachments or need rehosting. Decide the comment ordering and author attribution rules: comments loaded out of order, or all attributed to the API user, destroy the conversation history agents rely on.
-
Freeze and sign off the mapping spec
Version the spec, walk the support lead through it row by row, and get explicit sign-off. Any change after this point goes through change control — mid-flight mapping edits are how partial loads happen.
Help Scout → Deskpro specifics
- Custom Fields
- GET /v2/mailboxes/{id}/fields (per-mailbox)
- Custom field values
- Spot-check dropdown selections, date values, and text fields against source data. Type mismatches during import silently zero out field values rather than erroring in some Deskpro versions.
Don't move on until
- Every source field is mapped, deliberately dropped, or parked in a custom field
- Status, priority and channel value maps agreed with the support lead
- Mapping spec version-controlled and signed off
04 Test Migration Prove the pipeline on a small, representative slice.
Objective A pilot load into a Deskpro sandbox that reconciles cleanly and has been reviewed by real agents.
Keep these open
-
Stand up a Deskpro sandbox that matches production config
Create the custom fields, groups, brands, business hours and SLA policies first. A pilot into a default sandbox tests nothing, because the failures you care about are all configuration mismatches.
-
Pick a deliberately nasty pilot sample
Take 500-1000 records chosen for difficulty, not convenience: the longest ticket threads, tickets with the most attachments, non-Latin character sets, merged and split tickets, deleted requesters, and every status value. A clean random sample proves only that easy records are easy.
-
Run the load with masked data and instrument everything
Log every API request and response with its source record ID. When 40 records fail out of 10,000 you need to know exactly which ones and why, without re-running the whole batch.
PII Masker Never load real customer PII into a sandbox -
Measure real throughput against the rate limit
Record achieved records-per-hour under Deskpro's actual rate limits, including retries and backoff. Extrapolate to the full volume: if the maths says the full load exceeds your freeze window, you fix that now, not on cutover night.
Published rate limits are ceilings, not throughput. Assume real-world rates are meaningfully lower once retries and backoff are counted.
-
Reconcile the pilot and triage every failure
Diff source against target on record counts and field-level values. Every discrepancy gets a root cause and a fix — "probably fine" at pilot scale becomes thousands of broken records at full scale.
Migration Validation Tool Diff the pilot batch against source before scaling up -
Put real agents in front of the pilot data
Have two or three agents work sample tickets end to end in the sandbox. They find the things reconciliation cannot see: unreadable threading, missing context, macros that no longer make sense. Fix the mapping, then re-run.
Don't move on until
- Pilot batch reconciles to 100% on record counts
- Agents have reviewed sample tickets and confirmed they are workable
- Measured throughput extrapolates to a viable full-load window
05 Cutover Execute the switch inside a controlled, reversible window.
Objective All in-scope data live in Deskpro, agents working in the new system, and a rollback path that stayed available throughout.
Keep these open
-
Pre-load history before the freeze
Load closed tickets and contacts days or weeks ahead while Help Scout stays live. Only open tickets and the final delta need to move inside the freeze — this is the single biggest lever on window length.
Helpdesk Migration Planner Size the freeze window from Deskpro's real API limits -
Publish the runbook with times, owners and abort criteria
A timed sequence: freeze start, final export, delta load, channel switch, smoke test, go/no-go, agent switch. Name who does each step and the explicit condition that triggers a rollback. Decide the abort criteria before the night, when nobody wants to be the one to call it.
-
Freeze Help Scout and take the final delta
Stop new ticket creation, let agents finish in-flight replies, then export everything changed since the pre-load. Announce the freeze to the whole business, not just support — someone always tries to raise a ticket during it.
Tickets created during an unenforced freeze land in the old system and are the most common source of permanently lost data.
-
Load the delta and open tickets
Run the delta load, then reconcile counts before touching any channel. Do not repoint email until the delta has verified — an inbound ticket arriving mid-load is far harder to untangle than a few extra minutes of freeze.
Migration Validation Tool Confirm the final delta landed before you reopen -
Repoint channels and verify with live traffic
Switch email forwarding and MX or connector settings, update chat widgets and web forms, and re-authorise integrations. Then send real test tickets through every channel and confirm each lands, routes and triggers the right automation.
Email forwarding changes can take up to a full DNS TTL to propagate — check the TTL days in advance and lower it if needed.
Cron Expression Builder Schedule the delta syncs that run through the freeze -
Run the go/no-go and switch the agents
Walk the exit criteria with the decision-maker, call it explicitly, then move agents over with a named person on hand for the first few hours. Keep Help Scout read-only rather than cancelled — cancelling the old contract on day one removes your only fallback.
Help Scout → Deskpro specifics
- Initial Sync
- Migrate all historical data while your team continues working in Help Scout. Depending on volume, this runs for days. Use checkpoint/resume; do not attempt this as a single-run script.
- Delta Sync
- Schedule a cutover window (typically over a weekend). Pause incoming mail to Help Scout, run a final delta script using GET /v2/conversations?modifiedSince={freeze_timestamp} to catch everything created or updated since the initial sync completed, and load those tickets into Deskpro.
- DNS / Email Routing Cutover
- Update your email forwarding rules and MX records (or Help Scout → Deskpro inbox forwarding) to route mail to Deskpro.
Don't move on until
- Full historical load complete and counts matched
- Inbound channels repointed and verified with live test tickets
- Rollback decision point passed explicitly, not by default
06 Validation Prove the migration is complete, then close it out.
Objective Documented evidence that data, workflow and reporting all survived, and a signed acceptance.
Keep these open
-
Run the full reconciliation
Compare source and target on every object: total counts, counts by status, counts by group, attachment counts, and field-level spot checks on a random sample. Produce one report you can hand to an auditor.
Migration Validation Tool Reconcile Help Scout and Deskpro record-for-record -
Verify field completeness, not just record counts
Re-profile the loaded data and compare null rates per field against the source profile. Matching record counts with a field that silently arrived empty is the failure mode counts alone will never catch.
Data Profiler Prove field completeness held up through the load -
Rebuild reporting and compare against baselines
Recreate your core dashboards — volume, first response time, resolution time, CSAT — and compare to pre-migration figures for the same period. Explain every variance; a changed SLA calculation is a real finding, not a rounding error.
SLA and first-response metrics are usually recalculated from the loaded timestamps, so they will differ if any timestamp mapping was approximate.
-
Test the workflow layer end to end
Fire every trigger, automation, SLA escalation, macro and notification with a live ticket. Workflow does not migrate — it gets rebuilt — so it is untested until someone has actually watched it run.
-
Confirm compliance and produce the audit trail
Re-scan the loaded data for regulated fields, confirm retention and deletion policies are configured in Deskpro, and file the evidence with your PII decisions from the audit phase.
PII & Compliance Scanner Produce the compliance evidence your auditor will ask for -
Sign off, then decommission on a schedule
Get written acceptance against the Discovery success criteria. Keep Help Scout read-only for an agreed period (30-90 days is typical), take a final archive export, and only then cancel. Diarise the decommission date so it does not quietly renew.
Help Scout → Deskpro specifics
- Conversation count match
- Total tickets in Deskpro should equal total conversations exported from Help Scout (minus spam, if excluded). A discrepancy means missed conversations or redirect-following failures on merged conversations.
- Thread count per ticket
- Spot-check 50+ tickets: does each have the correct number of messages and notes? Pay special attention to tickets with forwarded threads.
- Attachment integrity
- Download a random sample of migrated attachments; compare file size and SHA-256 checksum against the originals downloaded during extraction.
- Customer-to-ticket linkage
- Verify tickets are associated with the correct Person record — not a duplicate created by a casing difference in the email address.
- Timestamp accuracy
- Confirm date_created on migrated tickets matches the original Help Scout conversation creation date — not the import run date.
Don't move on until
- Full reconciliation report attached to the project record
- Reporting baselines match pre-migration figures within agreed tolerance
- Formal acceptance signed and archive retention scheduled
Field mapping reference
The field-by-field mapping for each object. Use this as the starting point for your mapping spec.
Entity Equivalent
| Help Scout field | Deskpro field | Notes |
|---|---|---|
| Mailbox | Department | 1:1 mapping. Deskpro supports nested departments (e.g., Support > Technical, Support > Billing). |
| Conversation | Ticket | Status mapping requires translation (see below). |
| Thread (customer, reply, note) | Message / Note | Thread type field determines message direction. |
| Customer | Person | De-duplicate by email before import. |
| Company | Organization | Help Scout companies are loose associations; Deskpro orgs are first-class entities with formal membership. |
| Tag | Label | Direct 1:1 mapping. |
| Custom Field | Custom Field | Must be pre-created in Deskpro with matching types. Note the field IDs for API writes. |
| User (agent) | Agent | Create agents in Deskpro first; map by email. |
| Team | Agent Team | Rebuild team membership manually. |
| Saved Reply | Snippet | No bulk export API — must be recreated manually. |
| Workflow | Trigger / Automation | No export — must be rebuilt from scratch. |
| Docs Article | Knowledgebase Article | Separate API (Docs API v1) required for extraction. |
Thread Type Equivalent
| Help Scout field | Deskpro field | Notes |
|---|---|---|
| customer | Message (from person) | Inbound customer message. |
| reply | Message (from agent) | Agent reply — map createdBy.id to agent. |
| note | Note (internal) | Internal-only; not visible to customer. |
| message | Message (from agent) | Agent-initiated outbound (proactive). |
| forwardparent | (metadata only) | Log as internal note with forward context. |
| forwardchild | (new ticket reference) | Handle as a linked ticket or note. |
| phone | Message | Treat as inbound; tag with "phone" channel. |
| chat | Message | Treat as inbound; tag with "chat" channel. |
Risk matrix
Per-object risk for this pair. Plan extra validation around anything marked high.
| Object | Risk | Notes |
|---|---|---|
| Tickets (Conversations) | medium | Conversations map cleanly to Tickets in structure, but status translation, merged conversation redirects, and pagination at scale introduce meaningful risk of data gaps if not handled explicitly. |
| Messages (Threads) | high | Thread content is not included in the conversation list response and requires a separate API call per conversation, making it the most common source of empty ticket bodies in failed migrations. |
| Attachments | high | Attachments must be downloaded directly from thread attachment URLs before Help Scout access expires, and any delay or access lapse during extraction results in permanent data loss. |
| Contacts (Customers / People) | medium | Customers must be de-duplicated by email before import into Deskpro People, as duplicate entries will cause broken ticket-to-person associations throughout the migrated dataset. |
| Organizations (Companies) | medium | Help Scout companies are loose associations while Deskpro organizations are first-class entities with formal membership, requiring explicit relinking of People to Organizations after import. |
| Custom Fields | medium | Custom fields are scoped per-mailbox in Help Scout and must be pre-created in Deskpro with matching types and noted field IDs before any ticket data can be written via the API. |
| Agents (Users) | low | Agents map directly by email address between platforms and must simply be created in Deskpro first so their IDs are available for assignee mapping during ticket import. |
| Tags / Labels | low | Tags have a direct 1:1 mapping to Deskpro Labels and are a flat list with no hierarchical complexity, making this one of the lowest-risk entities in the migration. |
| Knowledgebase Articles (Docs) | medium | Docs articles require extraction via the separate Docs API v1 using HTTP Basic authentication rather than OAuth, adding a distinct authentication and extraction pathway that is easy to overlook. |
| Workflows and Saved Replies | high | Neither Workflows nor Saved Replies have a programmatic export path, meaning all automation logic and canned responses must be manually audited and rebuilt from scratch in Deskpro post-migration. |
The hard parts
What makes this specific migration difficult, beyond the mechanics.
No Native Importer Exists
Deskpro provides a built-in Zendesk importer but has no equivalent for Help Scout, requiring a fully custom Help Scout Mailbox API v2 to Deskpro REST API v2 extraction and load pipeline.
Thread Content Requires Separate API Calls
The Help Scout List Conversations endpoint returns only a truncated preview field, not full message bodies, meaning each conversation requires an additional GET /v2/conversations/{id}/threads call to retrieve actual content.
OAuth Token Expiry During Extraction
Help Scout bearer tokens expire after 48 hours, and large extractions spanning multiple hours require a checkpoint-and-resume pattern with automatic token refresh to prevent silent data loss mid-migration.
Status Model Incompatibility
Help Scout's four conversation statuses (active, pending, closed, spam) must be translated to Deskpro's constrained three-state model (Awaiting Agent, Awaiting User, Resolved), with non-standard pending usage requiring custom field workarounds.
Merged Conversation Redirect Handling
Help Scout returns HTTP 301 redirects for merged source conversations, and extraction scripts that do not follow redirects automatically will silently lose those conversations entirely.
Workflows and Saved Replies Unexportable
Help Scout Workflows and Saved Replies have no bulk export API and cannot be programmatically migrated, requiring full manual reconstruction of all automations and canned responses in Deskpro.
Tools used in this playbook
All free, all run entirely in your browser — nothing is uploaded.
FAQ
Does Deskpro have a built-in Help Scout importer?
No. Deskpro offers a built-in Zendesk importer but has no equivalent for Help Scout. You must build a custom pipeline using the Help Scout Mailbox API v2 for extraction and the Deskpro REST API v2 for loading.
Can I use Help Scout's CSV export to migrate to Deskpro?
No. Help Scout's native CSV export does not include message bodies, thread replies, internal notes, or attachments. It only covers reporting-level metadata. You must use the Mailbox API v2 to extract full conversation data.
How long does a Help Scout to Deskpro migration take?
For under 10K conversations, expect 1–2 weeks. For 10K–50K conversations, plan for 2–3 weeks. Datasets over 50K conversations with attachments and knowledge base articles can take 3–5 weeks, largely driven by API rate limits and QA time.
How do Help Scout statuses map to Deskpro statuses?
Help Scout's 'active' maps to Deskpro's 'Awaiting Agent', 'pending' maps to 'Awaiting User', and 'closed' maps to 'Resolved'. Deskpro does not support arbitrary custom statuses — it uses a fixed three-state model. Spam conversations should be skipped.
What Help Scout data cannot be migrated to Deskpro automatically?
Workflows, Saved Replies, Beacon configurations, per-conversation satisfaction ratings, and report dashboards cannot be exported via API. These must be manually recreated in Deskpro as Triggers, Snippets, Messenger config, and DPQL reports.