Gateway Settings

Settings › Gateway holds the values your mail system uses to send mail through mxHERO: your Transport Agent value, the option to process only mail that carries it, an optional Gateway Secret, SMTP-Auth credentials, allowed IP addresses, and custom headers. Read this page before you set up routing, and again whenever you rotate a value.

Before you begin

• You need an Owner or Administrator user in the Admin Dashboard.
• Know which routing architecture you use. See Routing architectures.
• Gateway Secret Authentication and SMTP-Auth Service Accounts take effect as soon as you use their buttons. The other sections take effect only when you click Save settings at the bottom of the page.

Transport Agent

The Allowed transport agent field shows your organization's Transport Agent value: 32 lowercase hexadecimal characters, unique to your organization. In this documentation it appears as <your Transport Agent value>, for example 3f9c….

Your mail system uses it in two headers:

To copy the value, click the copy icon ("Copy to clipboard") next to the field.

Warning: Your routing rule must skip messages that contain X-mxHero-Server, not X-mxHero-Transport-Agent. mxHERO removes the Transport Agent header, so a rule that tests for it never matches and mail loops.

Note: Older documentation called this value a "domain hash" and said to get it from support. It is now self-service on this page and applies to your whole organization, not one domain.

Generate a new Transport Agent value

Rotate the value if it was exposed, or as part of a security review. During rotation, mxHERO accepts both the new and the previous value.

1. Click the refresh icon ("Generate new transport agent") next to the field.
2. Read the warning and confirm. The new value appears, and the old value is kept as the previous value.
3. Update every routing rule that sets the header or tests X-mxHero-Server to the new value: Microsoft 365 mail flow rules, Google Workspace content compliance rules, border gateways.
4. Send test messages in each direction and check them in Reports › Email Flow Logs.
5. Back on Settings › Gateway, remove the previous value.

You can't generate another value while a previous one is still listed. Remove it first.

For Microsoft 365 PowerShell commands that update the rules, see Office 365 Configuration Service.

Only process email rules with transport agent header

This switch (sometimes called Strict Mode) controls what mxHERO does with mail that doesn't carry your Transport Agent value.

The switch is on for organizations registered since April 21, 2025, and off for older organizations unless someone changed it.

When to use each setting:

• Turn it on when every route into mxHERO adds the header: Microsoft 365 and Google Workspace loopback routing, and border gateways that add the header. It stops mxHERO from running your rules on mail that reaches it by another path.
• Turn it off when mail reaches mxHERO without the header, for example when your MX record points directly to smtp-in.mxhero.com (Inbound Border) or a gateway can't add headers.

To change it, use the switch, then click Save settings.

Important: If the switch is on and the header is missing or has the wrong value, mail is delivered without any processing and doesn't appear in Email Flow Logs. When test messages are delivered but missing from the logs, check this first.

Gateway Secret Authentication

A Gateway Secret is a second value that your mail system adds to every message it sends to mxHERO. It stops anyone who has learned your Transport Agent value from sending mail as your organization.

Once a secret exists, every message that carries your Transport Agent value must also carry:

X-mxHero-Transport-Agent-Secret: <your Gateway Secret>

mxHERO rejects a message with a missing or wrong secret with 550 Message rejected: invalid transport agent secret., and removes the header from messages it accepts.

Turn on the Gateway Secret

Warning: As soon as you generate a secret, mxHERO rejects every message that carries your Transport Agent value but not the secret. Do this in a quiet period and have your routing rules open and ready to edit, so the gap is as short as possible.

1. Click Generate new secret. The secret is created and saved immediately.

2. Copy the secret.

3. Add the X-mxHero-Transport-Agent-Secret header with that value everywhere you add X-mxHero-Transport-Agent:

   • Google Workspace: add a second custom header to each mxHERO content compliance rule.
   • Microsoft 365: a mail flow rule sets only one header. Create a second rule for each mxHERO rule, with the same conditions and the same X-mxHero-Server exception, that sets X-mxHero-Transport-Agent-Secret.
   • Border gateway: add the header next to the Transport Agent header.

4. Send test messages and check them in Reports › Email Flow Logs.

Rotate the secret

1. Click Generate new secret.
2. Choose how many minutes the previous secret stays valid: from 0 to 60. The page shows when the previous secret expires.
3. Update the header value in all your routing rules before that time.

Choose a period long enough to update every rule. With 0 minutes, the previous secret stops working immediately.

You can also remove the secret. Mail then no longer needs the header.

SMTP-Auth Service Accounts

SMTP-Auth credentials let a system that can't be identified by IP address or header (for example an application server, a scanner or a third-party gateway) authenticate to mxHERO with a username and password and relay mail through it.

1. Click Add user. mxHERO creates the credentials immediately:
   • Username: your organization ID followed by a dash and 4 random characters.
   • Password: 32 random hexadecimal characters.
2. Copy each value with its copy icon ("Copy username", "Copy password"). Click the eye icon to show the password.
3. In the sending system, configure:
   • SMTP server: smtp-relay.mxhero.com
   • Port: 587 or 25
   • Authentication: username and password (PLAIN, LOGIN or CRAM-MD5)
   • TLS: use STARTTLS if the system supports it.

You can have up to 2 users per organization. To delete one, click its trash icon ("Delete user") and confirm. A system using deleted credentials can no longer send through mxHERO.

Warning: These credentials can relay mail to any address. Store them like any other service password, and delete users you no longer need.

Allowed IP masks

Use this list to accept mail from your organization's senders only when it comes from your own mail servers. Leave it empty to accept such mail from any IP address.

1. Click in the Allowed IP masks box.

2. Type an IPv4 address, for example 203.0.113.25, and press Enter. Repeat for each address. Values in the wrong format are not added.

   

3. Click Save settings.

When the list has entries, mxHERO refuses mail whose envelope sender is in your organization if the connecting IP address is not on the list. The sending server gets 553 <recipient> address unknown. Mail to your users from outside senders is not affected.

Warning: Microsoft 365 and Google Workspace send from large, changing IP ranges that you can't list one address at a time. Use this setting only when your organization's outbound mail reaches mxHERO from a few fixed IP addresses, such as an on-premises server or a border gateway. Otherwise your outbound mail is refused.

Gateway Headers

Gateway Headers adds fixed headers to mail that mxHERO delivers for your organization, for example a header your gateway or archive uses to recognize processed mail.

1. Click Add Header. A row appears under Gateway Headers.

2. Choose the Direction:

   • In: added to inbound mail (to your users).
   • Out: added to outbound mail (from your users).
   • Both: added in both directions.

3. Enter the Header Name and Header Value.

   

4. Click Save settings.

Mail between two users of your organization receives all your gateway headers, whatever their direction. Header names that start with X-mxHero are reserved and are removed when you save. To remove a header, click the trash icon on its row, then Save settings.

Office 365 Connector

The Office 365 Connector section sets up Microsoft 365 routing for you with Add Connector. See Office 365 Configuration Service.

Verify

• Copy your Transport Agent value and compare it with the value in each routing rule. They must match exactly.
• Send a test message in each direction. Check that it appears in Reports › Email Flow Logs and that the delivered message carries X-mxHero-Server with your value. See Testing mail flow.
• Changes to this page are recorded in Reports › User Activity.

Troubleshooting

Related pages

• Routing architectures
• Office 365 manual configuration
• Google Workspace configuration
• Border gateways
• Network endpoints and IP addresses
• Mail not processed