Importing historical email into EspoCRM starts with mailbox scope, not settings
A team moving from another CRM or from a shared inbox setup usually wants past customer email visible on accounts, leads and opportunities from day one. The work is mostly deciding which mailboxes, which date range and which record matches matter. Once those decisions are made, the configuration itself is the documented IMAP fetch in EspoCRM, which is short to set up. Start by listing every mailbox that holds customer correspondence, then separate group mailboxes such as sales or support addresses from personal accounts, because the two are handled differently and mixing them creates ownership confusion later. Confirm the mail server's IMAP access and credentials for each mailbox with the mail administrator before anything is configured.
For each personal account, the Fetch since setting decides how far back EspoCRM imports. Setting it to a past date archives older messages, so the decision is how far back the business actually needs to search. Effort depends mainly on three things: the number of messages in scope, the number of mailboxes, and how much cleanup is needed afterward on records that were linked incorrectly or left unlinked. Ask your team to estimate message volume per mailbox by date range before choosing a cutoff, and do not assume a single global date fits every account. Confirm with your administrator how the mail server throttles large fetches, since a very large first pull may need to be planned in stages.
Plan the record matching rules before the first fetch. EspoCRM does not duplicate email records fetched by different email accounts, which matters when the same correspondence reaches several mailboxes, and it tries to link each incoming email to an appropriate Account, Lead, Opportunity or Case. Those automatic links depend on the addresses already stored on your records, so cleaning contact addresses first will improve results more than any setting change. Review a sample of linked and unlinked messages from each mailbox, record which matches are wrong, and agree who signs off on the cleanup before the full import runs.
What email history maps to in EspoCRM and what does not
This table compares common features of a source mail system with their closest EspoCRM equivalents for imported email. Read each row as a question to answer for your own mailboxes before the import is scheduled. The main takeaway is that messages can be archived and linked to CRM records, but the surrounding mail structure does not copy over automatically.
| Source feature | In EspoCRM after import | What to confirm before import |
|---|---|---|
| Personal mailbox history | Imported through a personal email account using Fetch since set to a past date, so older messages are archived in the CRM | Which mailboxes are in scope, and whether each owner agreed to their history being stored in the CRM |
| Shared or group inbox | Handled through a group email account, which is a separate account type from personal accounts | Whether the shared inbox should be imported as a group account, and which teams need access to its messages |
| Duplicate fetching across accounts | EspoCRM does not create duplicate email records when different accounts fetch the same message | How overlapping mailboxes, such as a shared inbox copied to several users, will be handled in the plan |
| Automatic linking to records | EspoCRM tries to link each incoming email to an appropriate Account, Lead, Opportunity or Case | Sample matches on real correspondence, because automatic linking can miss records that use unusual addresses or aliases |
| Unmatched messages | Messages that find no suitable record stay as emails without a related CRM record | How many unlinked messages are acceptable, and who will link or review them after the import |
| Folder structure | Source folders are not expected to become EspoCRM folders or categories automatically | Whether folder meaning must be preserved, and how it will be recorded in a field or a linked record instead |
| Mail rules and filters | Server-side or client-side rules from the source system are not carried over as-is | Which rules routed mail to specific people or teams, and how that routing will be rebuilt with EspoCRM settings |
| Old threads and conversation context | Messages arrive as individual emails, and threading across old replies depends on what the source headers preserved | Whether reply chains must appear as threads in EspoCRM, and whether that matters for your sales or service users |
| Attachments | Attachments are stored with the imported messages, subject to instance storage and file settings | Total attachment volume, retention rules for sensitive files, and where the instance keeps its file storage |
Documented paths for pulling email into EspoCRM
EspoCRM offers a few documented ways to get past correspondence into the CRM, and each one fits a different mailbox type and a different kind of record. The cards below cover the personal IMAP fetch, shared mailboxes, the administration settings that control linking, and CSV import for content that never arrived as email. Confirm each behavior against the documentation for the release you run before you commit to a plan.
Personal IMAP fetch with Fetch since
A personal email account connects to a mailbox over IMAP, and its Fetch since setting decides the earliest date EspoCRM will pull from. Setting a past date archives older messages into the CRM, so the date is the main lever for history. Check how many folders the account reads and whether the mailbox provider limits fetch volume, since a long history can be large. Confirm the IMAP configuration steps for your release in the user guide.
Shared mailboxes for group correspondence
A group or shared account, such as a support or sales address, holds correspondence that no single person owns. Its messages belong to the team rather than to one user, so the import is only as useful as the team's access settings. Decide which teams should see historical threads before the fetch starts, because records that land in the wrong visibility scope are hard to clean up later. Confirm how group accounts handle historical fetch in your release.
Email administration linking settings
The email administration settings govern how an incoming message is matched to an Account, Lead, Opportunity or Case. EspoCRM documents that it tries to link each email to an appropriate record, and it does not create duplicate email records when different accounts fetch the same message. Review the linking behavior with a sample mailbox before a full run, because matches on shared addresses such as generic domains can attach mail to the wrong customer. Confirm the settings available in your release.
CSV import for non-email records
Some history never arrives as email, such as call notes, meeting logs or exported correspondence kept in spreadsheets. The CSV import can create or update those records with field mapping, duplicate matching on chosen fields and a revert option for a bad batch. It cannot reconstruct a threaded email conversation, so treat it as a complement to the mailbox fetch rather than a substitute. Test a small file first and confirm the import modes available in your release.
Limits of each documented path
Each path has boundaries that affect scope. The IMAP fetch depends on mailbox access and provider rules, the linking logic depends on how well addresses match existing records, and CSV import carries no native email threading. Document which messages you expect to be linked and which will remain unattached, so reviewers know what counts as complete. Ask your administrator to confirm the exact limits of your release before you promise the business a result.
How a historical email import runs from inventory to cutover
This sequence moves past correspondence into EspoCRM in controlled stages, so each mailbox is tested, linked and verified before the old access is removed. The output is a documented cutover that your teams can trust.
Inventory mailboxes and retention needs
Start by listing every mailbox that holds customer correspondence, including shared group addresses, sales and support aliases, and personal inboxes of staff who have left or changed roles. For each one, record the owner, the protocol and host used for IMAP access, the earliest date your retention policy requires, and any mail that must not be imported. Your legal or compliance lead should sign off on the retention window before any configuration starts. The step is complete when you have a written inventory that maps each mailbox to a business owner and a date range, and when you have confirmed with your mail administrator that IMAP access is available for each account.
Pilot one personal and one group account
Configure one personal email account and one group account in a non-production EspoCRM instance, using a narrow Fetch since date so the pilot covers a small, known slice of history. Confirm that the group account is set up as intended and that the personal account fetches only mail from the chosen date forward. Check that the mailbox credentials are stored and that the account can be read without errors. The pilot is complete when a named reviewer confirms that the imported messages match the source mailbox for the chosen period, and the import log shows no authentication or connection failures.
Verify linking and duplicate handling
Review a sample of imported emails and check whether each one is attached to the right Account, Lead, Opportunity or Case. Look for messages that were linked to the wrong record, left unlinked, or linked to a record that the sales or support team no longer uses. Next, confirm that a message reachable through two accounts, such as a personal inbox that receives copies of a group address, appears only once in EspoCRM. Record the linking rules that need adjustment, such as how contacts and their email addresses are matched, and rerun the pilot after each change. The checkpoint is a signed-off sample with known exceptions documented for the business owner.
Run a parallel period with the old system read-only
Keep the source mailbox and any legacy archive available for lookup, but put them in a read-only state for staff who are verifying the import. During this stage, new correspondence should be checked against both systems for a short, agreed period so that gaps in fetching are caught while the old copy still exists. Ask the business owners to search for three or four recent customer threads they know well and confirm they appear in EspoCRM with the right links. The stage ends when those spot checks pass and no unexplained gaps remain in the fetch log.
Run the full historical import
Extend the Fetch since date to the full retention window for each account in the inventory, starting with the accounts that carry the most correspondence. Because large mailboxes can take time to fetch, monitor the scheduled background jobs and their logs rather than assuming completion. Confirm that the record count per account and the date range match what you expect from the source. Keep notes on any mailbox that fails or returns partial results, and retry those accounts separately. The step is complete when every inventoried account has a fetch log with no outstanding errors and the counts have been reconciled with the source.
Cut over and confirm access is the only path
Move day-to-day email handling to the new process, so staff use EspoCRM for correspondence lookup and continue fetching new mail through the configured accounts. Confirm that each account is fetching new messages and linking them as expected, and that the business owners can find the historical threads they need. Check that the old mail client or archive is no longer the default place people look for customer history. This checkpoint is passed when the business owners confirm they can work from EspoCRM for the agreed period and no open defects remain.
Decommission old mailbox access
Once cutover is confirmed, remove the stored IMAP credentials for historical imports, disable the retired accounts or fetch rules that are no longer needed, and revoke any delegated access that was granted only for migration. Keep the source archive under the retention terms your compliance lead approved, and record where it is held and who can access it. Update the inventory so every mailbox has a final status, owner and decommission date. The step is complete when the inventory shows no remaining migration-only access and your security team has confirmed the credential removal.
Group versus personal accounts: which mailbox should feed EspoCRM
The first decision in any historical email import is whose mailbox feeds EspoCRM, because that choice sets who owns the imported history and who can later see it. A personal mailbox connected to a user's own EspoCRM account is the natural fit when one person has carried most of a customer relationship. Its Fetch since setting controls the start point, so a past date pulls older correspondence into the CRM. A group or shared account, such as a sales or support address, suits correspondence that many people handled. Imported messages then belong to the team rather than to one individual, and they remain available after staff leave.
The main risk sits with personal mail. A personal account often contains messages unrelated to customers, including private, HR or legal correspondence. Once fetched with a long lookback, that material becomes searchable by anyone whose role can read the linked records, and it can also appear in the mailbox owner's own views. Before any personal account is connected, confirm with legal and HR which folders and date ranges are in scope, and check how the mailbox's own filters and access rules will interact with EspoCRM's role permissions. Visibility should then be tested with a non-admin user from each team, not assumed from the admin view.
Write the decision into the scope before work starts. Record which mailboxes feed the import, the date each one starts from, who owns each account, which roles or teams may read the imported emails, and who approves any change later. If a mailbox is shared by several teams, decide whether it should be split or whether visibility should follow the linked Account or Opportunity. Confirm with your own mail provider how IMAP access, app passwords and retention are handled for each account type, because these settings vary by provider and tenant.
What drives the effort and duration of email import
This table lists the factors that change how much work a historical email import takes and how long it runs, and whether each one is paid once or carries on after go-live. Use it to see which inputs to give a partner before asking for a fixed-scope quote, and which ones your own team can reduce in advance.
| Driver | Why it changes effort | One-time or ongoing | What to ask for or confirm |
|---|---|---|---|
| Number of mailboxes | Each mailbox needs its own personal account, connection settings, fetch date and test run, and group mailboxes need their own shared setup. | One-time | Confirm the full mailbox list, which are shared and which are personal, and who owns each one. |
| Years of history | A fetch since an early date pulls more messages, which lengthens the initial run and raises the number of records to check afterward. | One-time | Ask for the earliest date to import and an estimate of message counts per mailbox from your mail administrator. |
| Attachment volume | Large attachments increase storage use and transfer time, and they affect backup size and restore time. | One-time for the import, ongoing for storage | Ask for total attachment size per mailbox and confirm the storage location and retention rules for files. |
| Quality of contact and account records | Matching depends on accurate email addresses on Account, Lead, Opportunity and Case records, so gaps or stale data mean more manual linking. | One-time | Ask for a count of contacts with missing or duplicate email addresses before scoping the work. |
| Number of duplicate senders | Several contacts sharing one address, or one person using several addresses, complicates linking and the review of matches. | One-time | Ask for a list of addresses that map to more than one record and the rules for choosing the correct one. |
| Access to mailbox credentials | The import needs a working IMAP login for each mailbox, and unavailable or changed credentials stop the fetch and delay the schedule. | One-time, with ongoing upkeep if passwords rotate | Confirm who supplies credentials, whether app passwords or service accounts are allowed, and how they are rotated. |
| Server resources | Long fetches and attachment handling use PHP, database and background job capacity, which may need planning around cron execution. | One-time for the import, ongoing for capacity | Ask how the import will run in the background, what load the server can take, and when the run can be scheduled. |
| Cleanup of linked records | Wrong links, orphaned emails or records that need merging after the import add review time that scales with the volume of mail. | One-time | Ask how many links will be reviewed, who approves corrections, and whether a rollback plan is included in scope. |
What usually goes wrong with historical email and how to prevent it
Historical email import is less about the import itself and more about what becomes visible afterward. The risks below share one root cause: a mailbox carries far more history, and far more personal content, than the CRM was designed to hold. Each card names a prevention step you can settle before the first fetch runs.
Importing too far back
Setting Fetch since to an early date pulls in years of correspondence, including messages that predate your current retention policy or contain data no current user should see. Agree a cut-off date with legal and data protection owners before configuring the account. Then check a sample of imported records against that rule, and confirm who can see the Email entity under your roles.
Mis-linking to the wrong record
EspoCRM tries to link each incoming email to an Account, Lead, Opportunity or Case. Shared addresses, such as a generic billing mailbox used by several customers or a reseller domain, can attach messages to the wrong company. Before the import, list the addresses that appear on more than one record and decide whether they should be excluded or linked manually. Spot-check linked messages from each major customer group.
Personal mail leaking into team views
A personal mailbox fetched into the CRM can expose private messages to colleagues who have access to related records. Decide up front which mailboxes are group accounts and which are personal, and import personal mail only where the owner has agreed and the business purpose is documented. Review team visibility settings before the first run, not after.
Mailbox credentials stored insecurely
Importing requires an IMAP login, and a password saved in a shared configuration or a document is a common weak point. Use a dedicated mailbox account with read-only scope where your mail provider supports it, and store the credential only in EspoCRM's protected settings. Confirm with your identity team that the account is not tied to an administrator and that its password rotates under your normal policy.
Duplicate expectations across accounts
EspoCRM does not duplicate email records fetched by different email accounts. Teams often assume that a message sent to both a personal and a group mailbox will appear twice, or that a second import will not add anything. Test with one thread that reaches two configured accounts and confirm the result matches what your users expect before running the full import.
Unclear retention rules
Imported email becomes CRM data with its own lifecycle, and nobody may own its deletion. Write down how long historical messages stay, who can request removal, and how that interacts with backups and exports. Confirm with your data protection lead before the import, because a retention rule added later will not reach messages already stored.
Questions teams ask before importing email history
What does importing historical email into EspoCRM cost?
The cost is mostly the labor of the people doing the setup, scoping and checking, not a license fee, because the open-source edition of EspoCRM can be self-hosted for free according to the EspoCRM pricing page. Costs come from mailbox access and scoping decisions, configuring one fetch per account, the time spent reviewing how emails linked to records, and any custom work needed for linking rules. If you hire a partner, the quote follows from a written scope that lists which mailboxes, date ranges and record types are covered. One-time work is the initial import and tuning. Ongoing cost depends on whether you keep fetching new mail after the backfill and who maintains the mail server settings. Ask any provider to itemize these parts in the quote.
How long does a historical email import take?
Duration depends mainly on the number of mailboxes, how far back the date range reaches, the volume of mail per mailbox and how many review cycles you want before go-live. No supplied figure gives a general duration, so confirm the estimate against your own mailbox sizes. Start with one pilot mailbox over a short date range, check how many messages linked correctly, then widen the scope. Plan time for a decision on group versus personal accounts, for access approvals from your mail administrators and for a check of linked records after the first run. Your provider or internal team should show that plan in the written scope before work starts.
What does our internal team need to provide for the import?
Your team needs to provide working IMAP access to each mailbox in scope, a named owner who can approve which accounts are imported, and a clear decision on the start date for each mailbox. You also need to decide whether each mailbox is a group account or a personal account, because that decides how the fetch is configured. Provide a list of record types the emails should link to, such as Accounts, Leads, Opportunities and Cases, and a contact who can review the first results. Confirm that your mail host allows the IMAP connection from the EspoCRM server and that retention and privacy rules for historical customer correspondence have been signed off before any mail is copied.
Can our team import email history alone with the documented settings?
Yes, a technically capable team can usually do a small import using the documented settings, since EspoCRM's IMAP and SMTP configuration lets you set a Fetch since date on a personal email account so older emails are archived. The harder parts are design choices: deciding how group and personal accounts overlap, checking that links point to the right records, and keeping duplicates out when the same message reaches the CRM through more than one account. Teams that lack mail server, EspoCRM administration or privacy review experience often choose to bring in a partner for scoping and validation. A partner works within a fixed scope agreed in writing, and DeployOpen runs that kind of implementation inside your own infrastructure.
How does EspoCRM avoid importing the same email twice?
EspoCRM does not duplicate email records fetched by different email accounts, according to its email administration documentation, so the same message reached through a group mailbox and a personal mailbox should not create two records. Even so, you should test this on your own data before a full run. Use a pilot mailbox that is also a member of a group account, confirm that one record exists afterward, and check the behavior after each change to the fetch settings. Keep a written record of which accounts are in scope so that the import can be repeated without guessing which mailboxes were already processed.
What happens to email linking when a contact or account is missing?
When a matching record is missing, EspoCRM tries to link the incoming email to an appropriate Account, Lead, Opportunity or Case, according to its email administration documentation, but a missing contact may leave the message unlinked or linked to a broader record. The result depends on your data quality, so review a sample before a full run. Clean up contact email addresses, decide whether historical correspondence should create new Leads or stay unlinked, and document a manual review step for messages that do not match. Unlinked emails are still stored, and your team can link them later once the owner confirms the correct record.
What security and privacy checks apply to imported customer email?
Historical customer email often contains personal data, contract details and sometimes sensitive information, so treat the import as a data processing activity. Confirm which mailboxes are in scope, who can read imported messages inside EspoCRM through roles and teams, and how mailbox credentials are stored and rotated. The EspoCRM security documentation recommends enforcing a password policy, requiring two-factor authentication and restricting access by IP address, and these controls should apply to the account that fetches mail. Ask your privacy or compliance lead to approve the retention period for the archived messages. DeployOpen prepares systems and evidence for compliance assessments, but independent auditors issue any audit reports or certifications.
Which mail platforms and mailbox types need confirmation first?
Confirm that each mail platform supports IMAP access for the accounts you plan to fetch, since the import depends on that protocol according to EspoCRM's IMAP and SMTP configuration documentation. Check whether each mailbox is a group account shared by a team or a personal account owned by one user, because the fetch behavior and access controls differ. Ask your mail administrator about message retention limits, folder structure, and any rate limits that could slow a large backfill. Verify these points with your mail provider and in your own environment before you agree on a scope, because supported features can vary by platform and tenant.
Controlling who can see imported correspondence
Imported email is only as private as the roles and teams that can reach it, so set those before the first fetch runs. Historical messages arrive as normal email records linked to Accounts, Leads, Opportunities and Cases, which means anyone whose role grants read access to those records can see the correspondence attached to them. Review how the roles in your instance grant access to emails, and check team membership for the people who will work the imported history. The EspoCRM security documentation also recommends avoiding admin accounts for daily work, so the account running the import should be a dedicated administrative identity, not someone's everyday login. Confirm which access model applies to personal mailboxes versus group mailboxes before you decide who gets the fetch configured.
The EspoCRM security guidance points to a set of baseline controls that matter more once years of customer correspondence are in the system: enforcing a password policy, requiring two-factor authentication, limiting auth token lifetime, disabling password recovery for admins and restricting access by IP address. If you use OpenID Connect sign-in, note that EspoCRM's own 2FA is not compatible with OIDC, so your identity provider must enforce the second factor. Decide whether the CRM should be reachable from the open internet at all, or only from approved networks, and test that restriction against the imported data as well as against new records.
Retention and privacy obligations for old correspondence are a business and legal decision, not a configuration default. Ask your counsel and compliance lead which messages you are permitted to hold, for how long, and who may review them, before you choose a fetch date. Record those decisions so they can be checked later. DeployOpen can prepare the access controls, configuration records and supporting evidence for your compliance work, but it does not issue audit reports, attestations or certifications, and independent auditors or certification bodies make those determinations.
How DeployOpen scopes and delivers historical email imports
DeployOpen treats historical email import as a scoped piece of work on your own EspoCRM instance, not a one-off script. We agree which mailboxes, date ranges and record types are in play, build and test the import against a copy of your data, then document and hand over the result.
How we scope
- Inventory the mailboxes, shared and personal, that hold correspondence you need in EspoCRM.
- Agree the earliest fetch date per account and how far back history should reach.
- Confirm which Account, Lead, Opportunity and Case records should receive matched emails.
- Engagements are fixed-scope, with the scope, deliverables and timeline agreed in writing before work starts.
How we build
- Configure group and personal email accounts in your test instance, with fetch-since dates set to the agreed past date.
- Test linking rules against sample threads so matches to the right records can be checked before a full run.
- Verify that mail fetched through more than one account does not create duplicate email records.
- Run the import in stages against a copy of production data, recording counts and exceptions for each stage.
How we hand over
- Document the account configuration, fetch dates, linking behavior and the steps used to run the import.
- Walk your administrators through spot checks of linked records, unmatched emails and access permissions.
- Record known limitations, such as emails that could not be linked, so your team can review them later.
- Provide the runbook and change notes in a form your team can repeat for future mailbox loads.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover.
- Retainers can cover re-running imports, reviewing new mailboxes and checking behavior after EspoCRM upgrades.
- Ask any provider to confirm which mailbox protocols, server settings and permissions your environment requires.
