Google Workspace Configuration

This page shows how to route Google Workspace (Gmail) mail through mxHERO in the Google Admin console, and which Server and Relay Server values to set in mxHERO. It covers all four architectures. Choose your architecture first: see Routing architectures.

Before you begin

• You need a Google Workspace super administrator account. Sign in at admin.google.com.
• Copy the Transport Agent value from Settings › Gateway in the Admin Dashboard. In this page it is shown as <TA>. It is 32 lowercase hexadecimal characters, for example 585439da368cbc9d4fe026ab3795e8c7 (yours is different).
• Your domains must be added in mxHERO. See Organization and domains.
• To start with a pilot group, create the Google group first. See Selective routing.

Values used on this page:

Warning: Do not use smtp.mxhero.com for any Gmail host. Older guides used it. Use smtp-in.mxhero.com for inbound and smtp-relay.mxhero.com for outbound. Mixing up the two hosts is a common cause of loops.

Gmail settings changes can take up to an hour to apply to all users.

Which steps you need

No ARC setup is needed in Google Workspace. mxHERO ARC-seals every message it processes, and Gmail evaluates ARC seals automatically. There is no trusted-sealer list to edit.

Step 1: Configure the inbound gateway

This tells Gmail that mail from the mxHERO IP addresses comes from a gateway, so Gmail checks the original sender instead of mxHERO.

1. In the Admin console, go to Apps › Google Workspace › Gmail › Spam, phishing, and malware.

2. Select the top-level organizational unit.

3. Open Inbound gateway and click Configure (or Edit).

4. Under Gateway IPs, add the 8 mxHERO IP addresses.

5. Select Automatically detect external IP (recommended).

6. Leave Reject all mail not from gateway IPs clear.

7. Leave Require TLS for connections from the email gateways listed above clear.

8. Inbound Loopback only: set up message tagging so Gmail reuses the spam verdict from its first pass:

   • Select Message is considered spam if the following header regexp matches.
   • Regexp: ^X-Gm-spam: (0|1)$
   • Select Regexp extracts a numeric score. Set Message is considered spam if extracted numeric score is to Greater than or equal to 1.
   • Select Disable Gmail spam evaluation on mail from this gateway; only use header value.

   For Inbound Border, leave message tagging at its defaults.

9. Click Save.

Step 2: Add the inbound host (Inbound Loopback)

1. Go to Apps › Google Workspace › Gmail › Hosts and click Add route.
2. Name: mxHERO Inbound.
3. Specify email server: Single host. Hostname smtp-in.mxhero.com, port 25.
4. Under Options, leave Perform MX lookup on host clear. Select Require secure transport (TLS) and Require CA signed certificate.
5. Click Save.

Step 3: Add the inbound content compliance rule (Inbound Loopback)

This rule sends inbound mail to mxHERO, adds the Transport Agent header, and skips mail that mxHERO has already processed.

1. Go to Apps › Google Workspace › Gmail › Compliance.
2. Select the top-level organizational unit.
3. Next to Content compliance, click Configure (or Add another rule).
4. Content compliance: mxHERO inbound routing.
5. 1. Email messages to affect: select Inbound and Internal - receiving. Leave Outbound and Internal - sending clear.
6. 2. Add expressions that describe the content you want to search for in each message: select If ANY of the following match the message, then click Add and set:
   • Expression type: Advanced content match
   • Location: Full headers
   • Match type: Not contains text
   • Content: X-mxHero-Server: <TA>
7. 3. If the above expressions match, do the following: Modify message, then:
   • Under Headers, select Add X-Gm-Spam and X-Gm-Phishy headers. The inbound gateway (Step 1) reads these headers on the second pass.
   • Select Add custom headers and add header key X-mxHero-Transport-Agent, value <TA>.
   • Under Route, select Change route and choose mxHERO Inbound.
8. For a pilot group, click Show options and set Envelope filter › Only affect specific envelope recipients › Group membership (only received mail) to your group.
9. Click Save, then Save again at the bottom of the page if shown.

Warning: The expression must test X-mxHero-Server with Not contains text. If it tests X-mxHero-Transport-Agent, or uses Contains text, mail loops.

Step 4: Add the outbound host

1. Go to Apps › Google Workspace › Gmail › Hosts and click Add route.
2. Name: mxHERO Outbound.
3. Specify email server: Single host. Hostname smtp-relay.mxhero.com, port 25.
4. Leave Perform MX lookup on host clear. Select Require secure transport (TLS) and Require CA signed certificate.
5. Click Save.

Step 5: Add the outbound content compliance rule

1. Go to Apps › Google Workspace › Gmail › Compliance › Content compliance › Add another rule.
2. Content compliance: mxHERO outbound routing.
3. 1. Email messages to affect: select Outbound and Internal - sending. Leave Inbound and Internal - receiving clear.
4. 2. Add expressions: If ANY of the following match the message, then add:
   • Expression type: Advanced content match
   • Location: Full headers
   • Match type: Not contains text
   • Content: X-mxHero-Server: <TA>
5. 3. If the above expressions match, do the following: Modify message, then:
   • Select Add custom headers and add X-mxHero-Transport-Agent = <TA>.
   • Under Route, select Change route and choose mxHERO Outbound.
6. For a pilot group, click Show options and set Envelope filter › Only affect specific envelope senders › Group membership (only sent mail) to your group.
7. Click Save.

Important: Use this rule, not the Gmail Outbound gateway setting. The outbound gateway sends all mail to mxHERO with no Transport Agent header and no loop exception. Without the header, mxHERO does not run your rules when Only process email rules with transport agent header (Strict Mode) is on, and with Outbound Loopback the mail loops. If an older setup has smtp.mxhero.com or another mxHERO host in Outbound gateway, remove it after the rule is working.

Step 6: Allow mxHERO to relay through Gmail (Outbound Loopback)

1. Go to Apps › Google Workspace › Gmail › Routing.
2. Next to SMTP relay service, click Configure (or Add another rule).
3. Enter a description, for example mxHERO return relay.
4. Allowed senders: Only registered Apps users in my domains.
5. Authentication: select Only accept mail from the specified IP addresses, and add the 8 mxHERO IP addresses.
6. Encryption: select Require TLS encryption.
7. Click Save.

Steps 7–8: Set Server and Relay Server in mxHERO

1. In the Admin Dashboard, open Settings › Organization and domains › Domains.
2. Edit each domain:
   • Server: smtp.google.com. Required for every architecture, even outbound only.
   • Relay Server: smtp-relay.gmail.com for Outbound Loopback. Leave it empty for Outbound Standard. To send through a border gateway, enter its hostname (see Border gateways).
   • Leave MX Lookup off.
3. Save.

If the Server is missing or wrong, inbound mail can loop and bounce. See Domain Server and Relay settings.

Warning: Never use an MX lookup for a host that resolves to Gmail, in Gmail Hosts or in mxHERO. Mail goes straight back into the routing rules and loops. Always use the explicit hosts on this page.

Step 9: Update SPF

Add include:_spf.mxhero.com to your existing SPF record. Do not create a second SPF record. Note the leading underscore.

v=spf1 include:_spf.google.com include:_spf.mxhero.com ~all

For Outbound Standard, also set up DKIM signing for mxHERO. See SPF, DKIM and DMARC.

Verify

1. Create a test rule in mxHERO for a test user. See Testing mail flow.
2. Send a message from an outside account to the test user. In Gmail, open the message › More › Show original. Check that X-mxHero-Server is present and that ARC and SPF pass.
3. Send a message from the test user to an outside account and check its headers the same way.
4. Find both messages in Reports › Email Flow Logs.

Troubleshooting

Related pages

• Routing architectures
• Selective routing
• Domain Server and Relay settings
• Testing mail flow
• Removing mxHERO from mail flow