Importing historical email

One importer, one job: pull past mail out of an IMAP mailbox and thread it into tickets. What it carries over, and what it deliberately does not.

Leodesk has exactly one importer: a per-mailbox, one-time IMAP historical import that walks a folder over a date range and turns past messages into tickets. It is deliberately narrow, and it is worth reading the last section of this page before you plan a migration, because what it does not carry over matters as much as what it does.

Before you start

The import runs over the channel's own IMAP connection, so IMAP has to be configured and working first — see receiving customer email. If the host or username is missing, the import refuses to queue and tells you to save and test the IMAP details first, rather than queueing a job that will silently fail.

The options, and what each one does

• Date range. A since and an until date, both optional. The range is pushed down into the IMAP search itself, so the mail server filters rather than Leodesk downloading an entire mailbox and discarding most of it. On a large archive this is the difference between minutes and hours.
• Folder. Defaults to the channel's configured folder, or INBOX. Point it at an archive folder if that is where your answered mail actually lives.
• Skip automated mail. On by default. Filters out DMARC reports, bounce notifications and out-of-office replies, which otherwise dominate a real support mailbox and make the imported ticket list useless. Turn it off only when you want a genuinely complete archival copy.
• Mark imported tickets resolved. Off by default, but usually what you want. Historical mail has already been answered somewhere else; importing it as open floods your live queue with hundreds of tickets nobody needs to action.

Running it

The import is queued as a background job and returns immediately, so nothing depends on you keeping the browser tab open. While it runs, progress reports six counters:

total      messages matched by the date range
processed  messages read so far
created    new tickets opened
threaded   messages appended to an existing ticket
skipped    duplicates the importer had already seen
system     automated mail filtered out

You can cancel a running import; it stops at the next checkpoint and keeps whatever it has already brought in. There is no automatic retry — a long import that partially succeeds should not be silently restarted from the top — so if it fails partway, fix the cause and run it again. Re-running is safe, which is the point of the deduplication below.

Deduplication and threading

Every message is deduplicated by its Message-Id against two sources: a permanent record of everything this channel has imported before, and the messages already sitting on live tickets. The second check catches mail that arrived through the live poller or your forwarding rule before you ran the import.

That permanent record survives ticket deletion, which is a deliberate design choice. If you import a conversation, decide you do not want it and delete the ticket, the next import will not resurrect it. Your deletion is treated as an instruction rather than an accident.

Messages thread using the same logic as live mail — subject marker first, then the Message-Id and In-Reply-To header chain, then subject plus shared participants — so a long back-and-forth exchange imports as one ticket with a full thread rather than six disconnected ones.

Dates come from each message's own Date header, falling back to the IMAP internal date. Imported conversations therefore sort into their real chronological position instead of all appearing to have arrived on migration day.

Why importing does not wake anyone up

Imports run in a historical mode that suppresses the side effects a live message would trigger. Nothing is marked unread, no notifications or emails go out to agents, already-resolved tickets are not reopened by an old reply landing on them, and the mailbox's default assignee is skipped so an import does not dump a thousand tickets into one person's queue. Your team should not be able to tell an import is running except by watching the counters.

What the importer does not bring over

This is the part people get wrong, so it is worth being blunt. The IMAP historical importer moves email. That is all it moves. There is no Zendesk importer, no Freshdesk importer, no Intercom importer, and no generic help-desk migration tool. Leodesk connects to a mailbox over IMAP, and a mailbox contains messages — not the metadata another vendor layered on top of them.

Specifically, none of the following is imported:

• Tags and ticket categories from your previous system.
• Macros and canned responses.
• Agent accounts, roles and permissions.
• Customer records as such — contacts are derived from the senders of the messages that get imported, so a customer who never emailed you will not appear.
• Ticket status history, SLA history, and CSAT or satisfaction scores.
• Internal notes and any other conversation that never existed as an email.
• Custom fields and their values.

All of that is recreated during onboarding, and in practice it is a smaller job than it sounds. Invite your agents and build the roles you need, rebuild the handful of macros you actually use — most teams find they were carrying dozens and using six — and set up your automation rules and SLA policies to match how you work now rather than how you worked three years ago.

A migration that goes smoothly

1. Set up outbound and inbound first

   Verify your domain and get live mail flowing before importing anything, so you are not debugging two things at once. See sending as your domain.

2. Import a narrow slice

   Pick a single recent month, leave skip automated mail on, and turn mark resolved on. Check the resulting tickets look right: correct requesters, threads intact, sensible dates.

3. Widen the range

   Once you trust the output, run it again over the full period you care about. Deduplication means the overlap costs you nothing but processing time.

4. Rebuild the rest

   Roles, macros, SLA policies, automation rules and inbox views. Do this while the import runs.

Most teams import six to twelve months. Older mail is usually better left in the original mailbox as an archive you can search on the rare occasion you need it.