mxHERO works on your email in two ways: as a gateway that processes messages while they travel, and through mailbox connections that process mail already stored in mailboxes. This page explains both, and what happens when something goes wrong. Read it before you plan routing or build your first rule.
Two ways to process email
| Email in transit (gateway) | Email at rest (mailboxes) | |
|---|---|---|
| Rule target | Email Flow (and Forwarding Address) | User Mailboxes |
| How mxHERO gets the mail | Your mail system routes messages through mxHERO over SMTP. | mxHERO reads mailboxes through Microsoft Graph, the Gmail API or IMAP. |
| When rules run | Before delivery, on each message. | On a schedule, on mail already delivered. |
| Changes to mail routing | Yes | No |
| Typical uses | Replace attachments with links, hold or approve messages, block attachments, file a copy of every message | Archive old mail, file existing mail, thin out mailboxes |
You can use one method or both. A third, smaller path, Drag and Drop, files email that users drop into a watched Box folder.
Email in transit (gateway processing)
Your mail system sends messages to mxHERO's SMTP gateway. mxHERO runs your rules, then returns the message to your mail system or delivers it to the recipient's server.
Loopback routing: your mail system sends each message to mxHERO once, and mxHERO returns it marked so it is not sent again.
Inbound and outbound endpoints
- Mail that enters mxHERO for processing on its way in to your users goes to
smtp-in.mxhero.com. - Mail your users send out goes to
smtp-relay.mxhero.com.
Both accept connections on ports 25 and 587. See Network endpoints and IP addresses.
Loopback and border routing
- Loopback. Your Microsoft 365 or Google Workspace tenant receives the message first, then a routing rule sends it to mxHERO. mxHERO returns it to your tenant, which delivers it. This is the most common setup.
- Border. Your MX record, or a border gateway such as Proofpoint or Barracuda, sends inbound mail to mxHERO before your tenant receives it. mxHERO then delivers it to your tenant.
- Outbound. Your tenant sends outgoing mail to mxHERO. mxHERO delivers it to the recipient's server directly, or relays it back through your tenant or another gateway.
For each domain, mxHERO delivers inbound mail to the address in the domain's Server field, and can relay outbound mail through the Relay Server. See Routing architectures to choose a design.
How mxHERO recognizes your mail and prevents loops
Each organization has a Transport Agent value, found in Settings › Gateway. Your routing rule adds this value to each message in the X-mxHero-Transport-Agent header. When mxHERO returns the message, it adds the same value in the X-mxHero-Server header. Your routing rule must skip messages that already carry X-mxHero-Server, so a message never goes through mxHERO twice.
Important: Organizations registered since April 21, 2025 have Only process email rules with transport agent header (Strict Mode) turned on by default. With Strict Mode on, your rules run only on messages that carry your Transport Agent value. See Gateway settings.
What happens to each message
- mxHERO accepts the message and makes one copy per recipient, so each recipient can be treated differently.
- The sender's organization's rules run. If the recipient belongs to a different mxHERO organization, that organization's rules run next.
- Rules run in a fixed order of action types: S/MIME, Block Attachments, Temporary Hold, Request Approval, Copy Emails, Zip Attachments, Secure Email, Protect Attachments. When a rule holds, blocks or replaces the message, later rules in that pass do not run.
- mxHERO signs the message with DKIM (if you set it up), adds an ARC seal, and delivers it.
Files are uploaded to storage in the background, and the processed message is delivered when the upload finishes. Changes you make to rules take effect within about 1 to 2 minutes. How rules work covers matching and ordering in detail.
Email at rest (mailbox processing)
For User Mailboxes rules, mxHERO connects to mailboxes and processes mail that is already there. Mail routing does not change.
Mailbox processing: mxHERO reads stored mail, files it, and then changes the original only if the rule's action calls for it.
- What gets connected. An administrator grants mxHERO organization-wide access (Microsoft 365 admin consent or Google Workspace domain-wide delegation), or individual users authorize their own mailbox. IMAP servers are also supported. See Office 365 directory and mailbox access and Google Workspace directory and mailbox access.
- Which mail is processed. You choose accounts, a time range and folders. A rule can run once over existing mail, or run continuously. Continuous rules check for new mail about every 5 minutes, and mxHERO also receives change notifications from Microsoft 365 and Gmail.
-
What happens to the original. Copy Emails leaves it unchanged, and can add a label or category (default
mxHERO) to mark it as processed. Move Emails moves it to trash or deletes it. Protect Attachments replaces it with a copy whose attachments are links.
Warning: For Protect Attachments on mailboxes, the original message is permanently deleted after the copy with links is created, unless you select Move original email to Trash folder. Check this option before you save the rule. You can't change it later.
What happens when something fails
mxHERO is designed to fail open: if processing can't complete, your email is still delivered.
| Situation | What the recipient gets | What you see |
|---|---|---|
| A rule hits an error | The original message, unchanged | An error in Email Flow Logs and a notification |
| Cloud storage can't save the files (Protect Attachments, Secure Email, Zip with storage) | The original message with its attachments | A storage error in Email Flow Logs and a notification |
| Same, and the rule's More actions is set to bounce the email to the sender | Nothing. The sender receives a [BOUNCED] notice and can resend. |
A rejection in Email Flow Logs |
| Cloud storage is temporarily unavailable | Delivery waits while mxHERO retries for up to 45 minutes. Then the original message is delivered, unless the rule bounces the email to the sender: then nothing is delivered and the sender receives the [BOUNCED] notice. |
A notification that processing failed after retries |
| The message can't be read (malformed) | The original message, without rule processing | An entry in Email Flow Logs |
| Block Attachments matches | Nothing. The message is always stopped, by design. | A dropped message in Email Flow Logs |
Rules that copy mail (Copy Emails) never delay delivery. The original is delivered while the copy is saved, and a failed copy can be forwarded to an address you choose.
Note: If a recipient's mail server can't be reached, mxHERO keeps retrying for up to 24 hours before returning the message to the sender, like any mail server.
Comments
0 comments
Please sign in to leave a comment.