Team: Huntress Managed Email Security (ES)
Product: Microsoft 365, Google Workspace
Summary: Diagnose and resolve common Huntress Managed Email Security issues, covering setup, onboarding, mailbox status, detections, quarantine, and spam filtering, by reviewing symptoms, likely causes, and resolution steps.
In this Article
Before You Start
Setup and Authorization
Onboarding and Historical Ingestion
Mailboxes
Detections and Remediation
Quarantine and Release
Spam Filter
Expected Behavior During Early Access
Getting Help
Before You Start
Many unexpected behaviors stem from a tenant's current stage in the onboarding process. Huntress Managed Email Security (ES) progresses through these stages in order:
Authorization: A Global Administrator (Microsoft 365) or Super Admin (Google Workspace) authorizes the integration from ES > Dashboard > Configure a Mailbox.
Mailbox sync: Syncing finishes about 10–15 minutes after authorization.
Historical Ingestion: ES analyzes the last 30 days of mail. This process takes 12 hours to 2 days, depending on the tenant's size.
Passive Mode: ES flags malicious mail without removing messages. This stage lasts seven days after Historical Ingestion finishes.
Enforcement Mode: ES automatically remediates high-confidence malicious messages.
Spam filtering runs separately from these stages. For details, review Historical Ingestion, Passive Mode, and Enforcement.
Setup and Authorization
Use the scenarios in this section to resolve sign-in blocks, stalled setup dialogs, or permission questions when connecting a tenant.
Authorization Error When Connecting Microsoft 365
Symptoms
After signing in with the OAuth link, you see a generic authorization error instead of a Microsoft permissions screen.
You are not prompted for multi-factor authentication (MFA) before the error appears.
No new enterprise application appears in the tenant's Microsoft Entra admin center afterward.
Likely Cause
A Conditional Access policy in the tenant is likely blocking the sign-in, typically one that requires a managed device (Entra-joined, hybrid-joined, or compliant). Microsoft blocks the request before consent is granted. This often happens when an admin signs in from an MSP workstation or a personal device.
Resolution
In the Microsoft Entra admin center, go to Monitoring & health > Sign-in logs.
Filter by the admin account and the attempt time, then open the failed entry.
Check for the error code
50097("Device authentication is required"), which indicates a device-based Conditional Access requirement. Open the Conditional Access tab to see which policy applied, and check the Device info tab to confirm whether device identity was passed.Open the OAuth link in a private or incognito browser window from a device that is joined to or compliant in the customer's tenant.
If no managed device is available, review the tenant's Conditional Access policies with your security team. You can temporarily exclude the authorizing admin from the blocking policy, complete authorization, and remove the exclusion afterward.
For full steps, review the troubleshooting section of Add and Configure an Email Security Tenant.
Setup Stays Stuck After Authorizing
Symptoms
You completed the Microsoft or Google sign-in and clicked I've Authorized - Continue, but setup does not finish, or the tenant does not show a connected message source.
Resolution
Wait a few minutes. The Huntress platform periodically refreshes connection status, so updates may take a short time to appear on your dashboard.
If the connection still does not appear, cancel the current dialog and restart the flow from ES > Dashboard > Configure a Mailbox for the same organization.
Copy the newly generated OAuth link (do not reuse the earlier link) and open it in a private or incognito browser window.
Sign in as a Global Administrator (Microsoft 365) or Super Admin (Google Workspace) and approve the permissions.
Return to Huntress and click I've Authorized - Continue.
If the new attempt also fails, contact Huntress Support.
Missing Admin Rights in the Customer's Tenant
You do not need tenant admin rights yourself. Any Global Administrator (Microsoft 365) or Super Admin (Google Workspace) for the target tenant can open the authorization link from Configure a Mailbox and complete the process. Send them the authorization link, then click I've Authorized - Continue when they finish.
Note: During Early Access, authorization grants permissions to the Sublime application in the tenant. If you audit enterprise applications or consent grants in Microsoft Entra, you will see a Sublime application listed—this is expected behavior.
Onboarding and Historical Ingestion
Review these scenarios if historical scan results are delayed, a tenant switches modes unexpectedly, or third-party tools interfere with scanning.
No Historical Results Yet
Symptoms
The tenant is connected, but the Historical Ingestion summary does not appear.
Resolution
Historical Ingestion starts automatically when a message source connects; you do not need to trigger it manually.
Allow about 12 hours, and up to two days for larger tenants. You will receive a notification when ingestion finishes.
If more than two days have passed since authorization without results, contact Huntress Support.
Tenant Moved to Enforcement Mode Unexpectedly or Remains in Passive Mode
How It Works
Passive Mode lasts seven days after Historical Ingestion finishes. After seven days, you receive an email confirming that Enforcement Mode is scheduled, and the tenant moves to Enforcement Mode one day later.
-
You can adjust this behavior per tenant from the Email Security dashboard:
Select Activate Enforcement now to skip the remainder of Passive Mode.
Select "Opt out of automatic Enforcement" to keep the tenant in Passive Mode until you manually turn on Enforcement Mode.
If a tenant remains in Passive Mode past this timeline, check whether automatic Enforcement Mode was opted out for that tenant.
Phishing Simulation Emails Are Flagged
Likely Cause
No exclusions are enabled for your phishing simulation provider.
Resolution
Huntress Managed Security Awareness Training (SAT): The exclusion is built in and automatically enabled for every new tenant. No action is needed.
Other providers: Prebuilt exclusions are available for KnowBe4, Cofense, Proofpoint Security Awareness, HoxHunt, Microsoft Defender Attack Simulation, NINJIO, BullPhish, Adaptive Security, and Fable Security, but they are turned off by default. Contact Huntress Support to turn on the appropriate exclusion, ideally before the tenant moves to Enforcement Mode.
Mailboxes
To check mailbox status in Huntress, go to ES > Email Security Dashboard > View all Mailboxes and filter by status (Active, Inactive, or No Mailbox). For details, review Viewing and Managing Active Mailboxes.
Mailbox Shows as Inactive or No Mailbox
Likely Cause
The end user's license was removed, or the mailbox was deleted in Microsoft 365 or Google Workspace. ES detects the change, marks the address Inactive, and eventually removes it from the active monitoring list. Inactive addresses also stop counting toward your ES usage.
Resolution
If the change is expected (e.g., an offboarding), no action is needed. You do not need to deactivate the mailbox in ES separately.
If the change is unexpected, confirm in Microsoft 365 or Google Workspace that the end user still has an active license and provisioned mailbox.
New User Mailbox Is Not Listed
ES activates new mailboxes automatically when they are added to the tenant. If a new end user does not appear, confirm that they have an assigned license and a provisioned mailbox in Microsoft 365 or Google Workspace, then check the list again after a short wait.
On-Premises Hybrid Exchange Mailbox Is Not Protected
On-premises mailboxes in a hybrid Exchange deployment are not supported during Early Access, and no workaround is available. Shared mailboxes, distribution lists, Microsoft 365 groups, and service mailboxes are covered. For details, review Mailbox Coverage and Licensing.
Detections and Remediation
Use these scenarios to understand how ES evaluates detection rules, handles post-delivery remediation, and manages false positives or missed threats.
Legitimate Message Was Removed
Resolution
Log in to Huntress and go to the Email Security dashboard.
Locate the message in the quarantine log.
Select the restore option in the message review flow. You can add a label or comment explaining why you released the message.
Submit the review to return the message to the recipient's inbox.
Remediation can be undone, though Microsoft 365 enforces a time limit. Review Message Cannot Be Restored for details.
Legitimate Sender Keeps Getting Flagged
Releasing a single message restores that email but does not prevent future detections for that sender. During Early Access, partners can't manage exclusions directly. Contact Huntress Support with an example message so our team can configure an exclusion for that pattern, ideally during Passive Mode, before ES removes messages automatically.
Message Lists Detection Rules Without Removal
This behavior is expected. Matching a detection rule is not the same as receiving a malicious verdict. Rules act as the first pass, and deeper analysis assigns a final verdict:
Malicious: Quarantined when the tenant is in Enforcement Mode.
Spam or graymail: Moved to the Spam or Promotions folder if the Spam Filter is turned on.
Benign: Left in the inbox untouched.
The rule list shows which conditions matched, but it does not always explain the final verdict on its own.
Malicious Message Briefly Reached the Inbox
This behavior is expected. ES connects through the email provider's API rather than sitting inline like a traditional gateway. It analyzes messages after delivery and typically removes malicious emails within a short window. This API architecture also allows ES to remediate messages retroactively, including links that become malicious after delivery.
Many Messages Were Removed Across Multiple Mailboxes Simultaneously
This behavior is expected. ES groups related messages into a single attack campaign. When one message in a campaign is remediated, ES can act on all related messages across all affected mailboxes, including those delivered before the threat was identified.
Malicious Message Was Not Flagged
Report missed threats to Huntress Support with the message details so we can improve detection coverage.
Quarantine and Release
Review these scenarios if you run into retention limits when restoring messages, notice changes to restored calendar invitations, or have questions about end-user quarantine notifications.
Message Cannot Be Restored
Likely Cause (Microsoft 365)
Quarantined messages move to the mailbox's Recoverable Items\Purges folder. By default, Exchange retains these items for 14 days—a setting controlled by your Exchange deleted-item retention policy rather than ES.
The 14-day window starts when the message is originally received, not when ES quarantines it. If ES removes a message that arrived 12 days ago, only two days remain to restore it. Messages remediated during Historical Ingestion might already be past that retention window.
Resolution
Restore false positives as soon as possible.
If you need a longer recovery window, update the deleted-item retention setting in the Exchange admin center.
Calendar Invitations Look Different After a Restore
This behavior is expected. When a remediated message includes a calendar invitation, the calendar event is removed alongside the email. After a restore, the event returns as a placeholder that directs the end user to the original invitation for details and RSVP options. Placeholders omit the original organizer and invitee lists to prevent duplicate or outdated invitations from being sent to attendees.
End Users Are Not Notified When Mail Is Quarantined
Quarantine notifications and digests are not available during Early Access. Review quarantined items in the quarantine log on the Email Security dashboard. If end-user digests are important to your team or customers, share your feedback on the Huntress Feedback Portal.
Spam Filter
Use these scenarios to manage how ES sorts spam and graymail and to understand how organization-level settings behave.
Messages Move to Spam or Promotions
How It Works
-
When the Spam Filter is turned on, ES moves spam to the end user's spam folder and graymail (newsletters, marketing, and promotional mail) to a Promotions folder. Because these messages are not quarantined, end users can still access them.
Spam filtering runs independently from Passive Mode and Enforcement Mode, so it can move messages while a tenant is still in Passive Mode.
Spam and graymail share a single toggle.
Resolution
If a single message lands in the wrong folder, the end user can move it back to their inbox. ES uses these actions as feedback for future messages.
To turn off spam filtering for an organization, go to ES > Spam Filter and update the setting for that organization in the Organizations list. The change takes effect immediately.
Turning Off the Spam Filter Didn't Restore Messages
This behavior is expected. Turning off the Spam Filter applies only to incoming mail and does not move messages that were already filtered. End users can manually move previously filtered messages out of Spam or Promotions.
Changing the Spam Filtering Default Didn't Affect Existing Organizations
This behavior is expected. The account-level Spam Filtering Default applies only to organizations onboarded after you change the setting. To update an existing organization, change its setting directly in the Organizations list on the ES > Spam Filter page.
Expected Behavior During Early Access
The following behaviors are expected during Early Access and do not indicate a product issue:
ES does not create Huntress Incident Reports or Security Operations Center (SOC) escalations.
ES findings do not appear in other Huntress reporting, alerting, or integrations; all ES activity stays within the Email Security section of the Huntress platform.
ES requires no changes to MX records, mail routing updates, or endpoint agents, and it does not interrupt mail flow.
Feature availability and user interface (UI) layouts might change without notice during Early Access.
For details, review What Is Huntress Managed Email Security (ES)? and the Email Security Early Access FAQ.
Getting Help
If these steps do not resolve your issue, contact Huntress Support and include the following details:
Huntress organization name and affected tenant (Microsoft 365 or Google Workspace)
Action you were performing and the expected outcome
Approximate time of the issue, including the time zone
Affected message details (sender, recipient, subject, and received timestamp)
Screenshots of any error messages
For Microsoft 365 authorization errors: the authorizing admin account, the Correlation ID from the failed sign-in log, and screenshots of the Basic info and Conditional Access tabs