Home → Admin Manual → Email Setup and Troubleshooting → Email Has Stopped Flowing into HelpSpot

1.1. Email Has Stopped Flowing into HelpSpot

Updated: 21 Aug 2026, 12:35 PM EDT

Use these troubleshooting steps when no email at all is making it into a HelpSpot inbox.

1. Start with System Health

On HelpSpot 5.8.2 and later, Admin > System > System Health is the best place to start when troubleshooting missing emails, as it provides a lot of information about inbox status and errors.

In this case, you’ll want to check these things:

Mailbox Fetching — whether active mailboxes are polling, and the last successful fetch time for each one.
Queue Worker and Task Scheduler — whether the two background processes that drive mail retrieval are running.
Rejected Emails — whether inbound messages were received and deliberately rejected in the last 24 hours.

If Mailbox Fetching is stale but the queue worker and scheduler are healthy, you likely have a connection problem. If the queue worker or scheduler is unhealthy, mail collection is stopped system-wide.

If everything is green but a customer email never made it to your HelpSpot inbox, refer instead to the troubleshooting steps in Individual Messages Are Missing.

See Viewing and Tracking System Health for a full description of the page. On earlier versions, use the manual checks below instead.

2. Confirm the mailbox check is actually stuck

Go to Admin > Email Mailboxes and look at the Last Successful Check column. This is the last time HelpSpot connected to the email account successfully.

Current (within a minute or two) — connectivity is fine. The problem is downstream; go to Individual Messages Are Missing.
Stale — continue to step 2. The timestamp itself is a clue: line it up against server reboots, patch windows, firewall changes, or an upgrade, and you often have your cause.

3. Test the connection

Select the affected mailbox and click Test Connection.

An error is returned — the credentials or connection settings need attention. Follow the guide for your mailbox type:

No error is returned — HelpSpot can reach the mail server, so the problem is on the processing side. Continue to step 3.

4. Clear cache locks and restart workers

This is the most common fix for getting emails up and running again.

Go to Admin > Settings > Workers:

If any Cache Locks are listed, clear them. Mail collection usually resumes within a minute.
Use Restart Workers if work still appears stuck.

The interface for clearing cache locks was added in HelpSpot 5.6.15. On HelpSpot Cloud, this is always available.

Before 5.6.15 (self-hosted)

There is no Cache Locks interface on these versions, so clear the lock from the command line on your HelpSpot server. Two commands will do it, and the difference is how much they clear. Both are safe to run on a live system and neither touches your requests or email.

Command	What it clears	When to use it
`php artisan schedule:clear-cache`	Only the scheduler's locks, including the stranded mail-collection lock.	Try this first. It is the targeted fix and leaves your cached settings and configuration untouched, so there is no performance cost afterward.
`php hs cache:clear`	The entire application cache — the scheduler's locks plus cached settings, configuration, and data.	Use if the first command is unavailable on your version or does not resolve it. Everything cleared is rebuilt automatically on demand; expect slightly slower page loads for a short period while that happens.

Run them as the same user that runs HelpSpot:

On Linux that is typically the web server user, so sudo -u www-data php hs cache:clear.
On Windows, run the commands described in HelpSpot Command Line Tool.

Then watch Admin > Email Mailboxes. The Last Successful Check time should begin advancing on its own within a minute or two, with nothing run by hand. Anything waiting in the mailbox is not lost; it imports on the next successful check.

Why this happens: HelpSpot will lock while the mail-collection task runs, so two copies never run at once. If the server restarts while that task is mid-run — a reboot, a patch cycle, an upgrade — the lock is left behind with nothing to remove it. It carries a 24-hour safety expiry and will clear on its own eventually, but there is no reason to wait; clearing it manually restores mail collection immediately.

In this case, only mail collection is blocked. Automation rules, triggers, and notifications all keep running, so the system looks healthy from every other angle, and requests created through the API keep arriving normally while emailed ones stop. If API tickets are coming in and emailed ones are not, check for a stranded lock first.

Prevention: add a check of the Cache Locks section to your patching and upgrade routine, and clear anything listed once the server is back up.

5. Confirm the background processes are running

HelpSpot needs two processes running to retrieve mail:

The scheduler queues the mail retrieval jobs.
The queue worker picks those jobs up and does the actual retrieval.

If either is stopped, mail will not import no matter how healthy the mailbox connection is. To troubleshoot these:

On-premise Windows — confirm the HelpSpotQueue and HelpSpotSchedule services are both set to automatic and both running.
On-premise Linux — run sudo systemctl status supervisor to check the queue worker processes, and confirm the schedule:run cron entry is correctly configured.
HelpSpot Cloud — worker services are managed and monitored by UserScape. There is nothing to restart on your end. If mail is not fetching and the mailbox connection tests clean, contact HelpSpot Support.

See Troubleshooting On-Premise Worker Services and Troubleshooting HelpSpot Cloud Worker Services for more detail.

Less Common Causes of Missing Mail

High mail volume or many mailboxes. On Linux, raise numprocs in supervisord.conf and restart supervisor so more queue workers run in parallel.
Workers failing on large messages. Raise PHP memory_limit to 512M — in the php.ini the workers actually use, which is not always the one the web server uses. See Handling Large Email File Attachments.
Search indexing saturating the queue. After an upgrade, search index population can crowd out mail jobs. Confirm from the Search Index and Queue Depth rows on System Health, then contact Support before clearing jobs; removing the wrong jobs from the queue by hand can leave requests unindexed.

If You Still Need Help

If none of the above resolves it, submit a support request and include as much of the following as you have:

The System Health report (Download report for support on the System Health page), or the output of php hs health.
The Last Successful Check timestamp for the affected mailbox and the result of Test Connection.
Your helpspot.log file, or the email-related excerpts if it is very large. For more detail, turn on debug logging temporarily first.
Whether anything changed recently — an upgrade, a server migration, a patch window, or a mail platform change.

Knowledge Tags

This page was: Helpful | Not Helpful

Individual Messages Are Missing from HelpSpot →