Mail Not Processed – mxHero Help Center

Use this page when a rule does not act on a message you expected it to act on: attachments were not replaced, nothing was saved to cloud storage, or a message was not held. Start with the quick checks, then find your symptom in the tables.

Check these first

Find the message in Reports › Email Flow Logs. Search by sender, recipient, subject or Message-ID. Whether the message is there, and which events it has, tells you which table below applies. See Email Flow Logs.
Confirm the rule is running. In Rules › Rules List, open the Executing Rules tab. A disabled rule is listed only under All Rules.
Wait two minutes after a change. Rule and account changes take about 1–2 minutes to reach the mail engine. Messages sent during that time use the previous settings.
Confirm mail reaches mxHERO. In Microsoft 365, check that the mxHERO connectors and transport rules are enabled. The Office 365 Configuration Service creates the transport rules disabled when Save as disabled is left ticked (the default). In Google Workspace, check the routing or content compliance rule.
Check Reports › Notifications for execution_failed, execution_unexpected_error or storage_error near the time the message was sent.

The message is not in Email Flow Logs

If the message does not appear at all, mxHERO either never received it or received it without linking it to your organization.

Symptom	Cause	Fix
No entry for any message from a user or domain	Mail is not routed to mxHERO. The connector, transport rule or Google routing rule is disabled, scoped to other users, or missing.	Check the routing configuration for your architecture: Office 365, Office 365 Configuration Service, Google Workspace or border gateway. For selective routing, confirm the user is in the routed group; group changes can take a few minutes to apply in Microsoft 365 and Google.
No entry, and Only process email rules with transport agent header (Strict Mode) is on	With Strict Mode on, your rules run only on messages that carry your organization's Transport Agent header. Other messages pass through unprocessed and are not logged for your organization.	Make sure your routing rule adds `X-mxHero-Transport-Agent` with the exact value shown in Settings › Gateway. In a pure border (MX) inbound setup no header is added, so turn Strict Mode off. See Gateway Settings.
No entry after you generated a new Transport Agent value	Your routing rules still send the old value. mxHERO accepts both values only until you remove the previous one. A value that matches no organization is removed silently, and the message is processed as if no header were present.	Update the header value in every routing rule (and the loop-prevention exception) before you remove the previous value in Settings › Gateway.
Entry exists only in another organization you manage	The Transport Agent value belongs to the other organization. When the header matches, only that organization's rules run and only it sees the events.	Use the value from the correct organization's Settings › Gateway page.

The message is in Email Flow Logs, but the rule did not apply

Open the message and look at the events for the recipient. A rule that was evaluated but did not match shows an eval_filter_failed event with a reason code.

Reason code	What it means	Fix
`mail_content_without_attachments`	No attachment met the rule's attachment filter. Inline images are excluded by default.	Check the action filter (size, extensions, types). To include inline images, clear the inline-image exclusion. See Filters and Exclusions.
`mail_content_failed_to_check_filter`	Attachments were present but did not match the filter, or the message is a delivery report.	Compare the attachment names and types listed in the event with the filter.
`mail_content_failed_to_check_filter_policy`	The attachment filter policy did not match.	Test the policy's variables with a sample email. See Filter Policies.
`trigger_policy_no_match`	The rule-level filter policy did not match.	Same as above.
`mail_content_is_tnef`	The message is TNEF (`winmail.dat`). Protect Attachments, Secure Email, Zip Attachments and S/MIME skip TNEF messages.	Turn off TNEF in Microsoft 365. See Preventing TNEF Encapsulation.
`flow_filter_from_to`	The sender or recipient matched one of the rule's exclusions.	Review the exclusions in the rule.
`rule_shortcode_avoid_processing`	The sender put `#nomxhero` in the subject. Every later Protect Attachments, Secure Email and Zip rule is also skipped for that message.	Expected behavior. See Opting Out with #nomxhero.
`rule_shortcode_sender_not_managed_by_rule`	A subject hashtag was used by a sender who is not a managed account of the rule.	Add the sender as an account, or remove the hashtag requirement.
`security_policy_no_definition`	The rule's security policy resolved to no security definition.	Add a default condition to the security policy. See Security Definitions and Policies.
`copy_task_for_message_already_in_queue`	A copy of this message is already being saved.	No action needed.

If there is no event for the rule at all, the sender and recipient did not match the rule's target. Check these common causes:

Sender or recipient keywords. Anyone else means anyone who does not match the other side of the rule. It means "external" only when the other side is Organization. See Senders and Recipients.
Unknown accounts. Group, tag and organization matches require the account to exist in Settings › Accounts and Groups. Check that directory sync has imported the user.
Only managed accounts. With this filter on, the sender or the recipient must be a managed account of your organization.
Hashtag-triggered rules. A rule set to run only on a subject hashtag does not run without it.
Request Approval runs only on mail sent by your own organization's senders.
Target. The engine runs only rules with the Email Flow target. Mailbox rules run separately (see below).
An earlier rule took the message. Rules run in a fixed order by action type: S/MIME, Block Attachments, Temporary Hold, Request Approval, Copy Emails, Zip Attachments, Secure Email, Protect Attachments. Once a rule blocks, holds or replaces the message, later rules in the same pass are skipped. See How Rules Work.

The rule ran but failed

mxHERO fails open: if a rule fails, the original message is delivered unchanged.

Symptom	Cause	Fix
Event `rule_execution_failed`; notification `execution_failed` or `execution_unexpected_error`	The action hit an error. The original was delivered and later rules still ran.	Open the event to read the error. Fix the configuration it names, or contact support with the details listed in Getting Support.
Original delivered with attachments; Email Flow Logs Delivery status With storage errors	The upload to cloud storage failed.	See Storage Upload Failures.
Message delivered with no rule events	The message could not be parsed (malformed MIME). mxHERO delivers malformed messages without running rules.	Ask the sender to resend. If one sending system always produces this, contact support.

Mailbox rules (User Mailboxes target) are not processing

Mailbox rules read mail already in mailboxes through Microsoft Graph, the Gmail API or IMAP. They do not appear as Email Flow events in the same way. Open the rule from Rules › Rules List to see the per-account status and errors.

Symptom	Cause	Fix
Saving an Office 365 Protect Attachments mailbox rule asks you to re-authenticate or grant consent	Mailbox rules now use Microsoft Graph, which needs additional permissions.	Re-authenticate the account in Settings › Integrations › Accounts, or grant consent again on the Office 365 mailbox card in Settings › Integrations › Applications. See Office 365 Directory and Mailbox Access.
Notification `connection_error_max_retry`	An account failed to connect 20 times in a row. mxHERO then retries it every 8 hours.	Check the account's credentials and mailbox access.
Notification `task_finished_with_error`	A sync task finished with some messages in error.	Open the rule's account list and review the error details.
Move or mark-as-processed does nothing on an IMAP account	IMAP mailbox rules do not support post-processing.	Use Copy Emails for IMAP accounts. See IMAP and Individual Mailboxes.

Email Flow Logs status filters

Use the Delivery status filter to find affected messages quickly.

Filter	Shows messages that…
With rule errors	had a `rule_execution_failed` event
With errors	had an error but were delivered
With storage errors	had a storage error; pick an error code to narrow down
Dropped by rule action	were dropped by Block Attachments, a cancelled or rejected approval or hold, or a Forwarding Address rule
Retained Emails	are held by Temporary Hold or Request Approval