Home → Admin Manual → Email Setup and Troubleshooting → Troubleshooting O365 OAuth Mailboxes

1.12. Troubleshooting O365 OAuth Mailboxes

Updated: 6 Oct 2026, 11:03 AM EDT

This document provides troubleshooting guidance for HelpSpot Email Mailboxes connected to O365 email accounts. If you're experiencing trouble with mailflow or if you received an email error notification in HelpSpot, the tips below can help you identify and correct many common problems. 

Start with System Health

Before working through the steps below, check the System Health page (Admin > System > System Health). Its Mailbox Fetching check reports whether each active mailbox is polling for new mail and the time of its last successful fetch, and its Rejected Emails check surfaces the count of rejected inbound emails in the last 24 hours. It also reports whether the queue worker and task scheduler are running — if either shows a problem, go straight to the Queue Worker Services section below.

If you received a reconnect notification

As of HelpSpot 5.8.7, when Microsoft tells HelpSpot that a standard Microsoft mailbox's sign-in has expired or been revoked, HelpSpot sends administrators a mailbox error notification that reads: Microsoft authorization expired or was revoked. Reconnect this mailbox in its mailbox settings. HelpSpot can't collect new mail from that mailbox until it's reconnected.

You'll get one notification for the problem, not a new one every time HelpSpot checks the mailbox.

Advanced (self-managed) Microsoft mailboxes don't send this notification yet. For those, a stale Last Successful Check on the Email Mailboxes page is the sign to look for.

Common causes

• The password for the Microsoft account used to connect the mailbox was changed or reset.
• A Microsoft 365 administrator revoked HelpSpot's access, or changed sign-in or conditional access policies.
• The connection went unused long enough for Microsoft to expire it.

How to reconnect

• Standard Microsoft mailbox: generate a new API token at https://auth.helpspot.com in a private or incognito browser window, and paste it into the mailbox's settings under Admin > Email Mailboxes. See Mailbox Setup - Microsoft / Office 365 Email Configuration.
• Advanced (self-managed) Microsoft mailbox: open the mailbox under Admin > Email Mailboxes, click Reconnect to Microsoft, and sign in with the mailbox account in a private or incognito window. If the app registration's client secret has expired, create a new one in Microsoft Entra and paste it in first. See Mailbox Setup - Microsoft Advanced (Self-Managed).

After reconnecting, check that the mailbox's Last Successful Check on the Email Mailboxes page updates within a couple of minutes.

Connectivity

To begin with, the Admin > Email Mailboxes page displays each mailbox's Last Successful Check timestamp. If this reflects the current time, it means connectivity to the email account is working. If the Last Successful Check reflects any timestamp more than 1-2 minutes old, it means that was the last time that HelpSpot was able to successfully connect to the email account. Stale Last Check times sometimes offer clues to the cause of such issues (new firewall rules applied at a known time, network changes affecting on-prem HelpSpot servers, etc.)

If you see stale Last Check times, the first recommendation for restoring connectivity is to regenerate the API token  from https://auth.helpspot.com. Make sure you use an incognito/private browsing window to prevent any account caching issues. Generate the token in an incognito window and paste it into your mailbox settings in HelpSpot to attempt reconnecting to the email account.

If the Last Check is already current or if it still isn't refreshing after generating a new API key, the next most-likely cause is that the HelpSpot services aren't running correctly.

Queue Worker Services

• Troubleshooting HelpSpot Cloud Queue Worker Services
• Troubleshooting On-Premise Queue Worker Services

Other Issues

Lastly, if the services are running and you're still not getting incoming mail, you can temporarily bump up your logging output to include the details of each mail check action. Follow these directions to enable debug logging.

Contact Support

If none of the above tips resolves your email issue, reach out to HelpSpot Support for further troubleshooting assistance. You can include your helpspot.log file (or email-related stack trace excerpts from it if it's very large) when you submit your request.