Why EspoCRM email stops fetching and how to find the cause
Most EspoCRM email fetching faults sit in background job processing, mailbox connection settings or OAuth authorization, not in how EspoCRM displays email. When a shared or personal inbox stops updating, or updates hours after the mailbox has received messages, the people who depend on it notice first: sales representatives waiting for prospect replies, and support staff working a shared queue that no longer shows new threads. Fetching is a background task. EspoCRM connects to each configured mailbox, pulls new messages and links them to the right records. Because the work happens out of sight, a stalled job looks like a quiet inbox. A diagnosis is needed when a team reports a gap, and also after a server move, a mail provider change, or a password or consent change on the mailbox account. The EspoCRM server configuration documentation states that cron or a scheduled task must run background jobs, so the first question is whether that scheduler is running at all.
The cause usually shows in two places: the scheduled job trail and the application logs. Start by checking whether fetch jobs are being created on schedule, whether they complete, and whether they fail or wait in a pending state. A mailbox with no recent job activity points to scheduling, while a job that repeatedly fails points to the connection or the authorization. For Gmail and Outlook, an expired or revoked OAuth grant produces the same symptom as a wrong password, so confirm with the mailbox administrator that the connection is still permitted. Record which mailbox and which owning user are affected, when the last successful fetch happened, and what changed since then. That timeline lets you separate a single broken mailbox from a platform-wide scheduling fault, which decides whether you fix one account or the whole installation.
Plan the diagnosis before changing settings. Test the fix on one mailbox, confirm that new messages appear and link to the expected records, and only then correct the remaining accounts. Keep the cron user, the web server user and the mailbox owner documented, because permission problems on the host can stop jobs without any visible error in the interface. Ask whoever runs your servers to confirm the scheduler is active and that the EspoCRM files and log directory are writable by the account it runs under. Fetching gaps have a business cost: missed customer replies, duplicate outreach and records that show a thread as unanswered. If your team cannot reproduce the failure within a short window, treat it as an infrastructure question and gather the job and log evidence before the next change.
The diagnostic sequence to follow before changing settings
This sequence narrows a stalled EspoCRM inbox to one layer of the stack, from background job execution down to mailbox authentication, so that settings are changed only after the fault is located. Each step ends with a check that either clears that layer or points to where the fault sits.
Confirm background jobs are running at all
Start by checking that EspoCRM's background job processing runs on its own schedule, whether through cron or the daemon the server configuration documents. Someone with server access should confirm that the cron entry or scheduled task exists, runs under the account that owns the EspoCRM files, and is producing output or log entries at the expected interval. If nothing executes, every email fetch, workflow and scheduled job will stall together, so the fault sits in the scheduler, not in the mailbox. Do not move on until background execution is confirmed.
Check the scheduled job status for the fetch
Next, open the scheduled jobs list in the administration panel and find the job that fetches the inbox. Check its status, last run time and whether it is stuck in a running state from an earlier run. A recent successful run with no errors means the job is firing and the problem lies further down the chain. A job that never runs, or shows a failure or a stale running status, points to the job queue or to a process that stopped mid-run, so the fault is still in job processing.
Verify the web server user and file permissions
Confirm that the user the web server or PHP process runs as can read the EspoCRM installation and write to its data and cache directories. A mismatch between the cron user, the web server user and the file owner often produces fetches that appear scheduled but fail silently when they write logs or temporary files. Check the EspoCRM log for permission-denied messages from the same time window as a failed run. Clean permissions and a clean log mean this layer is cleared, while permission errors mean the fix belongs here and not in the mailbox settings.
Test the mailbox connection directly
With the job layer cleared, test the inbox connection from the EspoCRM email account settings using the connection test provided in the interface. Confirm the server host, port, encryption method and credentials. A connection that fails at the network level usually points to firewall rules, DNS or the mail server being unreachable from the EspoCRM host. An authentication failure points to the username, password or the account's mail access policy. A successful test with no fetched messages points to folder selection or filters, which should be checked before any change to the schedule.
Check OAuth tokens for Gmail and Outlook
For Gmail or Outlook accounts that use OAuth rather than a stored password, check that the authorization is still valid and that the access and refresh tokens have not been revoked or expired. Confirm the OAuth application configuration, redirect address and granted scopes match what was set up. Ask the mailbox owner whether the account password, security settings or tenant policy changed recently, because those events can revoke tokens. A failed token refresh in the log points to re-authorization, while a valid token with no fetched messages moves the investigation back to fetch frequency and linking.
Review fetch frequency and incoming email linking
Last, compare the configured fetch interval with what the business expects, and confirm that the job is not queued behind heavier background work that delays it. Then check a sample of messages that did arrive to see whether EspoCRM linked them to the expected records. Messages that were fetched but not attached point to the linking rules, while messages that were never fetched point to an interval that is too long or a queue that is too busy. The sequence is complete when each layer has been cleared or assigned a specific fault, and only then should settings be changed.
IMAP, Gmail OAuth and Outlook OAuth: what breaks in each
IMAP is the most direct connection method because EspoCRM authenticates to a mail server you name, with a host, port, encryption mode and a username and password or app credential. When an IMAP inbox stops updating, the cause is usually one of these settings or a rejected login rather than a fault in the CRM's record matching. Start by confirming that the server accepts the same credentials from a mail client on the same network, since that separates a server-side problem from an EspoCRM configuration problem.
- Server host and port: Confirm the host name resolves from the EspoCRM server and that the port matches the encryption mode the mail provider requires.
- Encryption setting: A mismatch between the port and the encryption mode, such as plain text sent to a TLS port, produces connection errors that look like login failures.
- Username format: Some providers expect the full email address as the username, and others expect a separate login name. Confirm the exact format with your mail administrator.
- Password or app credential: Providers that require app-specific credentials or block basic password logins will reject the stored password even when it works in a webmail client.
- Failed logins: Repeated failures can trigger provider lockouts or rate limits, so fix the credential before enabling the fetch job again.
Check the exact settings screen and provider requirements against the current EspoCRM docs and your provider's documentation, since no verified steps for those screens were supplied.
Gmail connections that use OAuth do not store a mailbox password in EspoCRM. Instead, a Google account owner grants consent, and EspoCRM holds tokens that it uses to request mail. Failures here usually involve consent that was never completed, access tokens that need refreshing, or grants that the user or the Google account administrator later removed. The official Google extension for EspoCRM is the supported path for this integration, so confirm that it is installed and at a version compatible with your EspoCRM release before troubleshooting the account itself.
- Consent screen: A connection that was started but not approved, or approved under a different Google account, will appear linked while fetching nothing.
- Token expiry: Access tokens expire and must be refreshed. A refresh that fails leaves the inbox stale even though the setup looked correct.
- Revoked grants: If a user removes EspoCRM's access in their Google account, or an administrator restricts third-party access, the stored grant stops working.
- Workspace policies: Organization-level controls on third-party apps can block consent or mail access for every user at once.
- Extension status: A disabled or outdated Google extension can stop token refresh and fetching without any obvious error in the user interface.
Confirm the current consent steps, scopes and Google policy requirements in the Google extension documentation and your Google Workspace admin console before changing the connection.
Outlook connections through Microsoft 365 use the same token model as Gmail: a user or administrator consents to access, and EspoCRM refreshes tokens to fetch mail. The failure points are similar, but the administrative layer is different because Microsoft 365 tenants often have their own application consent rules, conditional access policies and admin approval steps. The official Outlook extension is the supported integration for this path, and it should be checked for version compatibility before the account-level work begins.
- Admin consent: Tenants that require administrator approval for applications will block user-level consent, and the connection will look half finished.
- Conditional access: Policies that restrict sign-in by location, device or risk can reject token requests from the EspoCRM server.
- Token expiry and refresh: Expired or invalidated refresh tokens, for example after a password change or session revocation, stop fetching until the account is reconnected.
- Revoked grants: Removing the application from the user's consented apps, or an administrator revoking it, breaks the connection silently.
- Mailbox permissions: Shared or delegated mailboxes need the correct access rights, or fetching returns nothing for mail that the connected user cannot see.
Confirm the current consent flow, required Microsoft permissions and tenant policy requirements with your Microsoft 365 administrator and the Outlook extension documentation.
Fetch settings and when each one fits
This table compares the email fetch choices you make in EspoCRM: how often inboxes are checked, which folders are monitored, shared or personal mailboxes, and whether background processing runs from cron or a daemon. Read each row for the situation it suits and the load or freshness trade-off it creates, then confirm the exact options in your version's admin screens and documentation before you change production settings.
| Setting | When it fits | Trade-off | What to confirm |
|---|---|---|---|
| Shorter fetch frequency | Sales or support teams who expect replies to appear in records within minutes | More mail server connections and more scheduled job runs, which adds load on the database and mail provider | Confirm the interval options and any rate limits with your mail provider |
| Longer fetch frequency | Mailboxes that receive low volume or where a short delay in linking is acceptable | Records can look stale, and users may believe a reply was never received | Check how the delay appears in the Scheduled Job log before blaming the mailbox |
| Monitoring only the inbox folder | Teams that file or sort mail in a mail client and want fewer folders processed | Mail moved to other folders by rules or users is not linked to records | List every folder your users rely on and test a message in each one |
| Monitoring several folders | Teams that route customer mail into folders such as Sent or project folders | Each extra folder adds fetch work and more matching for the same messages | Confirm which folders hold mail that should appear in CRM records |
| Shared mailbox | Support, sales or billing addresses handled by a group through one account | One credential and one fetch cycle serve many users, but access must be controlled through teams and roles | Confirm which team can see messages and whether replies are sent from the shared address |
| Personal mailbox | Account owners who need their own correspondence linked to their own records | Each user adds a separate fetch and separate credentials to maintain, including OAuth renewals | Check who owns each credential and how it is renewed when a password or consent changes |
| Cron-driven processing | Smaller installs or simple setups where the server already runs scheduled jobs reliably | Jobs run only at each cron tick, so work can queue behind other jobs during busy periods | Confirm the cron entry runs as the web server user and that the Scheduled Job log shows regular runs |
| Daemon-driven processing | Larger volumes of jobs or mailboxes where queued work must not wait for the next cron tick | A separate long-running process needs supervision, restart handling and monitoring of its own | Confirm the daemon is supervised by the server and check the parallel process settings before enabling it |
How incoming email gets linked to records
When an inbox looks empty in EspoCRM, the message may have been fetched but not attached to any record the user can see. EspoCRM associates an incoming email with records by matching the sender and recipient addresses against the email addresses stored on contacts, accounts, leads and, where configured, cases. If no record matches, the message can sit in the mailbox without appearing on the timeline of the customer you expect. Start by confirming that the sender's exact address is stored on the right contact or lead, because a different address on the same person, a typo or a shared mailbox will break the match. Then check that the record actually exists and is not a duplicate that the user cannot access under their team and role permissions.
Next, check whether anything changes the outcome after the message is saved. A before-save script configured in the Entity Manager, an API before-save script, or a Formula Script used in a workflow or BPM process can set, clear or reassign fields that the linking depends on, such as the parent record or the assigned user. Review those scripts for conditions that skip or alter linking when a field is empty or unexpected. A simple test helps: send a message from a known contact to the monitored inbox, then compare the stored email record with the contact record it should link to. Document the result for each sender type your teams use.
The exact matching rules, including how multiple matching records are handled, how case and domain-based matching behave and which entities are searched first, depend on the EspoCRM version you run. Confirm them in the EspoCRM documentation for your version before you change data or write scripts around them. If the answer is unclear for your deployment, ask the vendor or test in a non-production copy, since changing linking logic on a live instance can move or duplicate records that your teams rely on.
Security points to handle while fixing mail fetching
Fixing a stuck inbox usually means changing mailbox settings, which touches credentials, tokens and the people allowed to edit them. The cards below cover the security decisions to make before and after the fix, using the guidance in EspoCRM's security documentation as the baseline.
Store mailbox credentials and tokens carefully
IMAP passwords and OAuth tokens for Gmail and Outlook give EspoCRM ongoing access to a mailbox, so they need the same care as other service secrets. Confirm how your EspoCRM version stores mailbox credentials and OAuth tokens, who can read them in the database and backups, and what happens to them when a mailbox is disconnected. Record where each secret came from so it can be rotated during the fix.
Use dedicated mailbox accounts
A shared or personal mailbox used for the fetch test may hold far more mail than the CRM needs. A dedicated mailbox or service account limits what EspoCRM can read and makes it clear whose access is in use. When troubleshooting, avoid connecting a personal mailbox just to see if fetching works, and confirm that the account's folder and permission scope matches the intended shared inbox.
Restrict who can change mail settings
Changing an inbox's server, folder or credentials can redirect incoming mail or expose a mailbox to the wrong account. Limit edits of email account settings to a small group of administrators, and avoid using the main admin account for daily work. Review the change history after troubleshooting to confirm that only the intended settings changed.
Apply the password and 2FA policy
The security docs recommend enforcing a password policy and requiring two-factor authentication for users. Mail troubleshooting often involves admins resetting passwords or reconnecting accounts, so confirm that these resets follow the same policy. Note that EspoCRM's own 2FA is not compatible with OIDC, so check which sign-in method your admins use before relying on it.
Limit auth token lifetime
The security docs advise limiting authentication token lifetime, which affects how long a stolen session can be used. Shorter lifetimes may force re-authentication during long troubleshooting sessions, so plan that step with the admin team. Also check that password recovery is disabled for admin accounts, as recommended, so that a mail-related reset cannot be used to take over an admin session.
Questions teams ask before fixing EspoCRM email themselves
Can our own team diagnose EspoCRM email that stops updating?
Yes, if someone on your team can read the server logs, check the cron or daemon setup and sign in to the mail provider's admin console. Most stalled inboxes come down to a scheduled job that is not running, a wrong IMAP or SMTP setting, or an expired OAuth grant. Diagnosis gets harder when several people share a mailbox, when the fetch runs through custom scripts, or when the team does not have an administrator who can change server configuration. Start by listing which of those three checks your team can do without waiting on someone else.
What makes an EspoCRM email fix take more or less effort?
The main drivers are the number of mailboxes, the authentication method and whether custom code touches the email flow. Ten shared mailboxes on plain IMAP usually take less investigation than three Microsoft 365 mailboxes that each need OAuth consent, tenant policy checks and a test of token refresh. Custom before-save scripts, workflows or hooks that run when email is linked to records add another layer to read and test. Ask any partner to break the scope down by mailbox count, provider, authentication type and custom code, and to state what is excluded.
How long does a typical EspoCRM email diagnosis take?
No duration can be stated without knowing your access and mailbox count, so treat any single number as unreliable. A diagnosis is quicker when the administrator can open the logs, the scheduled job history and the mail provider's console during the first session. It is slower when access must be requested in stages, when the provider's tenant administrator needs to approve changes, or when the fault only appears under load. Ask for the phases, the access each phase needs and the point at which findings are reported in writing.
What does the work need from our team before it starts?
Plan for four groups of access and time from your side. Your EspoCRM administrator needs an admin account that is not used for daily work, plus access to the server or container host. Mailbox owners need to confirm which inboxes matter and be available to test sends and replies. Whoever manages Google Workspace or Microsoft 365 needs to open the provider console and approve OAuth applications. Someone must also agree who approves any configuration change. Put these named people and their availability into the written scope.
Does fixing email fetching require changing security settings?
It can, and each change should be reviewed before it is made. Switching an account to OAuth, changing IMAP ports or allowing new IP addresses all affect your security posture. The EspoCRM security documentation recommends restricting access by IP address and requiring two-factor authentication for users, so confirm that email fixes do not weaken those controls. Ask for a list of every setting that will change, the reason for each change and how it will be reverted if it causes a problem.
When should we bring in a partner for EspoCRM email problems?
Bring in a partner when the fault spans several systems, when your team has already tried the standard checks without a result, or when email is business-critical and nobody in-house can own the fix. A partner is also useful when the mail flow depends on custom scripts or when the same problem needs to be prevented across many mailboxes. Keep the scope fixed in writing before work starts, including what is diagnosed, what is changed and what is handed back as documentation.
What ongoing costs come after the email fix is done?
The one-time cost is the diagnosis and any configuration work. Recurring costs come from keeping mailboxes healthy: checking scheduled job status, renewing or re-consenting OAuth grants when providers change rules, and reviewing logs after EspoCRM upgrades. Your mail provider's licensing and any EspoCRM extension fees are separate and depend on your plan. Ask any partner whether ongoing checks are included in the fixed scope or offered as a retainer, and request a written quote that separates these items.
What a fixed-scope mail fetching review covers
A fixed-scope review of EspoCRM email fetching starts with a written scope that names the failing path before any change is made. In practice that means diagnosing which link breaks: the scheduled job that fetches mail, the mailbox connection (IMAP or an OAuth-authorized Gmail or Outlook account), the user or shared mailbox the inbox belongs to, or the step that attaches incoming messages to records. The scope should state which of these were tested, which were ruled out, and what evidence was collected, such as scheduled job status and the relevant log entries. It should also say which systems are in reach, including the server, the mail provider's admin console and the EspoCRM instance itself, because access drives how much of the diagnosis is possible.
Once the cause is known, a written scope typically covers configuration fixes to the mailbox settings and the job runner, and reconfiguration of OAuth consent and redirect settings where the provider connection uses it. Verification belongs in the scope too: test messages sent to the monitored mailbox, checked for fetch timing, correct record linking and absence of duplicates. The reader should ask the provider to list each verification step and what the client must confirm, such as whether a test account or a copy of the mailbox is available. The final deliverable is usually handover notes covering the settings changed, the credentials and their owners, and the checks the internal team should repeat after future changes.
Most DeployOpen engagements are fixed-scope, so scope, deliverables and timelines are agreed in writing before work starts, and any change beyond that scope is agreed in writing before it proceeds. Where email fetching needs ongoing attention, such as after mail provider policy changes or EspoCRM upgrades, support can be arranged as a retainer instead. Before requesting a quote, confirm with your own team who will approve credential changes, which mailboxes are in scope, and whether a maintenance window is needed for the server. A quote follows from that written scope, and DeployOpen does not publish a price list.
How to verify the inbox updates reliably after the fix
This sequence proves that the fix holds across several scheduled cycles, that incoming messages land on the right records, and that the team knows what to watch after handover. It turns a one-time repair into a monitored, repeatable state.
Send test messages from known addresses
Someone on the admin side sends three or four test messages from addresses the team controls, such as a personal mailbox, a shared inbox and an external test account, with distinct subject lines that name the test. Send them at different times of day so that the check covers more than one scheduled run. The step is done when every message is visible in the mailbox that EspoCRM monitors, so the mail server has accepted them before EspoCRM is asked to fetch them. Record the send time and subject line for each message in the test log, because you will compare them against fetch times in later steps.
Confirm the fetch and linking outcome
Check that each test message appears in the expected Email record, in the correct folder or inbox view, within the window you observed during diagnosis. Open each record and confirm that it links to the intended Contact, Account, Lead or Case. Check for duplicate Email records, which can indicate a second fetch path or a repeated run. The step is done when every test message is linked to the intended record and none is duplicated, and any mismatch is noted with the matching rule that caused it.
Watch scheduled job runs across several cycles
Using the scheduled job view in the admin panel, follow the email fetch job across several consecutive cycles, not just the first run after the change. Note each run's start time, completion status and whether it ran as a cron-driven or daemon-driven process, as configured in your environment. Confirm that the job does not remain stuck in a running or pending state between cycles. The step is done when a complete set of runs shows successful completion and the timings match the expected interval, with a short written record of any run that was skipped or failed.
Check logs for errors after each cycle
Review the EspoCRM application log and, where your server exposes them, the web server and PHP error logs for the period covered by the test cycles. Look for repeated authentication failures, connection timeouts, TLS errors and any entries that reference the mailbox or its configured account. Compare entries against the test send times so you can tell fetch errors from unrelated noise. The step is done when the logs for the verification window show no new fetch-related errors, or when each remaining error has an owner and a planned action.
Repeat the test after a credential or token refresh
For OAuth-connected mailboxes, confirm that a token refresh completes without manual intervention and that fetching continues afterward. Ask the mailbox owner to re-authorize only if your diagnosis showed that a refresh is required, then send one more test message and confirm that it is fetched. For IMAP mailboxes, confirm that the stored password or app credential still works. The step is done when a post-refresh test message is fetched and linked correctly, which shows the fix survives the credential lifecycle rather than only the initial configuration.
Document the monitoring to keep
Write a short monitoring runbook that names the checks to repeat, who performs them, and how often your team reviews them. Include the scheduled job status view, the log locations, the expected fetch behavior for each mailbox, and the escalation path if a job stops or a mailbox stops updating. Store it alongside your other EspoCRM operations documentation. The step is done when the runbook is reviewed by the admin owner and the team that handles support, and each named check has a clear pass or fail condition that someone can act on without re-reading this troubleshooting work.
How DeployOpen scopes and supports EspoCRM mail fixes
DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, including EspoCRM instances running in your cloud accounts, data centers or air-gapped networks. For a mail problem, that means the work happens where your mail server, database, web server and cron or daemon already run, and the evidence stays with you. DeployOpen is a Chainscore Labs company. It does not hold a vendor partnership or certification for EspoCRM, so the scope below is defined by the engagement itself rather than by any reseller relationship.
Most engagements are fixed-scope, so the written statement of work should name the exact symptoms, the mailboxes and user types involved, the mail providers (IMAP, Gmail or Outlook OAuth), the cron or daemon setup and the access you will grant. Ask for the deliverables in writing: the diagnosis, the configuration changes, a runbook covering the scheduled jobs and fetch settings, and a short test plan that proves a message sent to a monitored inbox appears on the expected record. Timelines and any dependency on your mail provider's policies should also be stated in that document, along with what happens if the root cause sits outside the EspoCRM host.
Ongoing support, upgrades and continuous testing are available as retainers, which suits teams that change mail providers, add Google or Microsoft 365 integrations or upgrade EspoCRM on a regular cycle. A retainer covers the monitoring and response you agree in advance, while the one-time diagnosis is priced from the written scope. Before you sign, confirm who holds the administrator and OAuth credentials, how changes are recorded and how a fix would be rolled back. DeployOpen does not publish a price list, so request a quote built from that scope.
