Exchange Integration with HIN Gateway¶

This guide explains how to configure Microsoft Exchange (Online and On-Premises) to route mail through the HIN Gateway gateway for S/MIME signing and encryption.

Overview¶

HIN Gateway acts as a mail relay between external mail servers and your Exchange environment. Two integration patterns are supported:

Pattern A - Exchange Online as primary MX with transport rules:

flowchart LR
    I1 --> EO --> TR --> C --> S1 --> EO
    E2 --> TR2 --> OC --> S2 --> I2
    I1["Internet"]
    I2["Internet"]
    EO["Exchange Online"]
    E2["Exchange Online"]
    TR["Transport Rule"]
    TR2["Transport Rule"]
    OC["Outbound Connector"]
    C["Connector"]
    S1["HIN Gateway"]
    S2["HIN Gateway"]

Pattern B - HIN Gateway as primary MX:

flowchart LR
    I1 --> mx15 --> mx20
    EO --> TR --> OC --> HG --> I2
    I1["Internet"]
    I2["Internet"]
    mx15["HIN Gateway (MX priority 15)"]
    mx20["Exchange Online (MX priority 20)"]
    EO["Exchange Online"]
    TR["Transport Rule"]
    OC["Outbound Connector"]
    HG["HIN Gateway"]

In both patterns, you need:

DNS records pointing to the HIN Gateway server
Outbound connector - routes mail from Exchange to HIN Gateway
Inbound connector - accepts mail from HIN Gateway into Exchange
Transport rule - triggers the outbound connector for external recipients

Prerequisites¶

Before configuring Exchange, ensure:

HIN Gateway is installed and running (deployment instructions)
You have the HIN Gateway server's public IP address (referred to as <HIN Gateway_IP> below)
You have the mail hostname of the HIN Gateway server (referred to as <MAIL_HOSTNAME>, e.g. mail.example.com)
You know your mail domain (referred to as <YOUR_DOMAIN>, e.g. example.com)
You have Exchange admin access (Exchange Admin Center or on-premises Exchange Management Shell)
DNS records are configured per the DNS Setup Guide (A, MX, SPF at minimum)

Part 1: DNS Setup¶

See the DNS Setup Guide for complete instructions on configuring A, MX, SPF, PTR, DMARC, and DKIM records.

At minimum, before proceeding with the Exchange configuration below, you need:

A record: <MAIL_HOSTNAME> pointing to <HIN Gateway_IP>
MX record: <YOUR_DOMAIN> with HIN Gateway at higher priority (lower number) than Exchange
SPF record: ip4:<HIN Gateway_IP> and ip4:<HIN_SEALER_IP> added to your domain's TXT record (see DNS Setup Guide - SPF for sealer IPs)

Part 2: Exchange Online Configuration¶

Step A: Create the Outbound Connector (Office 365 → HIN Gateway)¶

This connector routes outbound mail from Exchange Online to the HIN Gateway relay server.

Navigate to the Exchange Admin Center - Connectors
Click "+ Add a connector"
Connection from: Select "Office 365"
Connection to: Select "Your organization's email server"
Click "Next"
Connector name: Enter a descriptive name, e.g.:

From Office 365 to HIN Gateway relay server

Check "Retain internal Exchange email headers"
Click "Next"
Use of connector: Select "Only when I have a transport rule set up that redirects messages to this connector"
Click "Next"

Tip

This is important - the connector won't route any mail by itself. It will only be used when triggered by the transport rule created in Step C.

Routing: Select "Route email through these smart hosts"
Enter the HIN Gateway server IP address: <HIN Gateway_IP>
Click "+" to add it, then click "Next"
Security restrictions: Select "Any digital certificate, including self-signed certificates"
Click "Next"

Note

HIN Gateway's MTA (Stalwart) accepts opportunistic TLS on inbound connections. Selecting "any digital certificate" ensures connectivity even with self-signed certificates.

Validation email: Enter a valid email address for your domain (e.g. user@<YOUR_DOMAIN>)
Click "+", then click "Validate"
Wait for validation to complete, then click "Next"

Tip

For validation to succeed, the HIN Gateway server must be running and accepting mail on port 25.

Review the settings and click "Create connector"
On the confirmation screen, click "Done"

Step B: Create the Inbound Connector (HIN Gateway → Office 365)¶

This connector accepts mail from the HIN Gateway relay server into Exchange Online.

From the Connectors page, click "+ Add a connector"
Connection from: Select "Your organization's email server"
Connection to: Shows "Office 365" (automatic)
Click "Next"
Connector name: Enter a descriptive name, e.g.:

Receive mail from HIN Gateway relay server

Check "Retain internal Exchange email headers"
Click "Next"
Authenticating sent email: Select "By verifying that the IP address of the sending server matches one of the following IP addresses that belong exclusively to your organization"
Enter the HIN Gateway server IP address: <HIN Gateway_IP>
Click "+" to add it, then click "Next"

Note

This tells Exchange Online to trust mail from this specific IP address, bypassing additional spam/authentication checks for mail that has already been processed by HIN Gateway.

Review the settings and click "Create connector"
Click "Done"

Verify Connectors¶

After creating the connectors (including the Send to MX connector from Step D), the Connectors page should show:

Status	Name	From	To
On	Receive mail from HIN Gateway relay server	Your org	O365
On	From Office 365 to HIN Gateway relay server	O365	Your org
On	Send to MX	O365	Your org

Step C: Create the Transport Rule¶

The transport rule redirects all outbound mail through the HIN Gateway outbound connector, except mail originating from HIN Gateway itself (to prevent mail loops).

Navigate to Exchange Admin Center - Rules
Click "+ Add a rule" → "Create a new rule"
Rule name: Enter a descriptive name, e.g.:

Relay all mail to HIN Gateway except mail coming from it

Apply this rule if: Select "The recipient..." → "is external/internal" → "Outside the organization"
Click "Save"

Note

This condition ensures only outbound mail (to external recipients) is redirected through HIN Gateway.

Do the following: Select "Redirect the message to..." → "the following connector" → select the outbound connector created in Step A (e.g. "From Office 365 to HIN Gateway relay server")
Click "Save"
Except if: Click "+" to add an exception
Select "The sender..." → "IP address is in any of these ranges"
Enter the HIN Gateway server IP address: <HIN Gateway_IP>
Click "Add", verify the IP is listed, then click "Save"

Warning

This exception is critical - it prevents mail loops. Without it, mail from HIN Gateway arriving at Exchange Online would be redirected back to HIN Gateway in an infinite loop.

Review the rule summary. It should show:
Apply this rule if: The recipient is located Outside the organization
Do the following: Redirect the message to the connector "From Office 365 to HIN Gateway relay server"
Except if: The sender IP address is in one of these ranges: <HIN Gateway_IP>
Click "Next", then "Next" again, then "Finish", then "Done"
Enable the rule: The rule is created in a disabled state. Click on the rule in the list and toggle "Enable or disable rule" to "Enabled"

Tip

Do not forget to enable the rule - it will not work until enabled.

Step D: Outgoing to MX (Send to MX Connector and Rule)¶

After HIN Gateway has processed (signed or encrypted) an outbound message, it hands the message back to Exchange Online through the inbound connector from Step B. Exchange Online then has to deliver it to the recipient's mail server. The "Outgoing to MX" setup does this: a dedicated Send to MX connector sends the message to the MX of the external recipient, and the outgoing_to_mx transport rule redirects the processed messages to that connector.

Create the Send to MX Connector (Office 365 → Partner Organization)¶

From the Connectors page, click "+ Add a connector"
Connection from: Select "Office 365"
Connection to: Select "Partner organization"
Click "Next"
Connector name: Enter a descriptive name, e.g.:

Send to MX

Make sure the connector is turned on
Click "Next"

Note

The connector name can be chosen freely. If you use a different name, select that name in the outgoing_to_mx rule below.

Use of connector: Select "Only when I have a transport rule set up that redirects messages to this connector"
Click "Next"

Tip

Like the outbound connector from Step A, this connector does not route any mail by itself. It is only used when the outgoing_to_mx rule below redirects a message to it.

Routing: Select "Use the MX record associated with the partner's domain"
Click "Next"
Security restrictions: Leave "Always use Transport Layer Security (TLS) to secure the connection" unchecked, so that no security restrictions apply
Click "Next"

Note

This connector delivers mail to any external recipient. Requiring TLS or a specific certificate here would block delivery to recipient servers that do not meet those requirements.

Validation email: Enter an external email address (outside your organization)
Click "+", then click "Validate"
Wait for validation to complete, then click "Next"
Review the settings and click "Create connector"
Click "Done"

The connector summary should show:

Mail flow scenario: From Office 365, to Partner organization
Name: Send to MX
Status: On
Use of connector: Use only when I have a transport rule set up that redirects messages to this connector
Routing: Use the MX record associated with the partner's domain
Security restrictions: None

Create the outgoing_to_mx Transport Rule¶

This rule routes outbound messages that come back from HIN Gateway to the Send to MX connector. It recognizes these messages by the outgoing message header.

Navigate to Exchange Admin Center - Rules
Click "+ Add a rule" → "Create a new rule"
Rule name: Enter:

outgoing_to_mx

Apply this rule if: Select "The message headers..." → "matches these text patterns"
Header name: outgoing
Text pattern: outgoing_<YOUR_DOMAIN> (e.g. outgoing_example.com)
Click "Save"

Note

The outgoing header must already be on the message when it returns from HIN Gateway. In the HIN reference setup it is added by a separate rule (set_header) that applies when the sender is located inside the organization and sets the message header outgoing to the value outgoing_<YOUR_DOMAIN>. Without this header, the outgoing_to_mx rule never matches.

Do the following: Select "Redirect the message to" → "the following connector" → select "Send to MX"
Click "Save"
Except if: Leave empty
Click "Next" to open the rule settings:
Rule mode: "Enforce"
Severity: "Not specified"
Leave "Activate this rule on" and "Deactivate this rule on" unchecked
Check "Stop processing more rules"
Leave "Defer the message if rule processing doesn't complete" unchecked
Match sender address in message: "Header"
Click "Next", then "Finish", then "Done"
Set the priority: Click on the rule in the list, click "Edit rule settings" and set Priority to a higher priority (lower number) than the transport rule from Step C, e.g. 1
Click "Save"

Warning

The priority and "Stop processing more rules" are critical. The rule must be evaluated before the Step C rule and must stop further processing. Otherwise a message returning from HIN Gateway can be redirected to HIN Gateway again instead of being delivered to the recipient.

Review the rule details. They should show:
- Rule name: outgoing_to_mx
- Mode: Enforce
- Severity: Not specified
- Set date range: Specific date range is not set
- Senders address: Matching Header
- Priority: 1
- For rule processing errors: Ignore
- Apply this rule if: 'outgoing' header matches the following patterns: 'outgoing_<YOUR_DOMAIN>'
- Do the following: Route the message using the connector named "Send to MX" and Stop processing more rules
Enable the rule: The rule is created in a disabled state. Toggle "Enable or disable rule" to "Enabled"

Tip

Do not forget to enable the rule - it will not work until enabled.

Part 3: On-Premises Exchange Server Configuration¶

For on-premises Exchange Server (2016, 2019), the setup is similar but configured through the Exchange Management Console (EAC) or Exchange Management Shell (PowerShell).

Send Connector (On-Premises → HIN Gateway)¶

Create a Send connector to route outbound mail through HIN Gateway:

Exchange Management Shell (PowerShell):

New-SendConnector -Name "To HIN Gateway Relay" `
  -AddressSpaces "SMTP:*;1" `
  -SmartHosts "<HIN Gateway_IP>" `
  -SmartHostAuthMechanism None `
  -DNSRoutingEnabled $false `
  -SourceTransportServers "<YOUR_EXCHANGE_SERVER>"

Exchange Admin Center (GUI):

Navigate to Mail flow → Send connectors
Click + to create a new connector
Name: "To HIN Gateway Relay"
Type: Select "Internet"
Network settings: Select "Route mail through smart hosts", add <HIN Gateway_IP>
Smart host authentication: Select "None"
Address space: Add * (all domains) or specific external domains
Source server: Select your Exchange transport server(s)

Receive Connector (HIN Gateway → On-Premises)¶

Create or modify a Receive connector to accept mail from HIN Gateway:

Exchange Management Shell (PowerShell):

New-ReceiveConnector -Name "From HIN Gateway Relay" `
  -Bindings "0.0.0.0:25" `
  -RemoteIPRanges "<HIN Gateway_IP>" `
  -TransportRole FrontendTransport `
  -Usage Custom `
  -AuthMechanism ExternalAuthoritative `
  -PermissionGroups ExchangeServers

Exchange Admin Center (GUI):

Navigate to Mail flow → Receive connectors
Click + to create a new connector
Name: "From HIN Gateway Relay"
Type: Select "Frontend Transport"
Network adapter bindings: Leave default or bind to specific IP
Remote network settings: Remove the default 0.0.0.0-255.255.255.255 and add only <HIN Gateway_IP>
Authentication: Check "Externally Secured"
Permission groups: Check "Exchange servers"

Transport Rule (On-Premises)¶

Create a transport rule to redirect outbound mail through the Send connector:

Exchange Management Shell (PowerShell):

New-TransportRule -Name "Relay outbound via HIN Gateway" `
  -SentToScope NotInOrganization `
  -RouteMessageOutboundConnector "To HIN Gateway Relay" `
  -ExceptIfSenderIpRanges "<HIN Gateway_IP>"

Exchange Admin Center (GUI):

Navigate to Mail flow → Rules
Click + → "Create a new rule"
Name: "Relay outbound via HIN Gateway"
Apply this rule if: "The recipient is located..." → "Outside the organization"
Do the following: "Redirect the message to..." → "the following connector" → "To HIN Gateway Relay"
Except if: "The sender IP address is in..." → add <HIN Gateway_IP>

Part 4: HIN Gateway-Side Configuration¶

Automatic Configuration (Default)¶

By default, Stalwart automatically discovers where to deliver processed mail by looking up MX records for each domain configured via the dashboard's /mail page. It filters out its own hostname and uses the remaining MX entries as delivery targets.

This works when:

Your domain has MX records pointing to both HIN Gateway and Exchange
HIN Gateway has a higher-priority (lower number) MX record than Exchange

Manual Override via the dashboard¶

If you want all outbound mail from HIN Gateway to go to a single Exchange endpoint (e.g. Exchange Online Protection), set the relay host through the dashboard's /mail page (e.g. [smtp.office365.com]). The dashboard sends the value to mtaconf's REST API and the daemon applies it to Stalwart.

Note

A single relay host sends all mail through one server and does not support per-domain routing. For multiple domains routing through different Exchange servers, use the per-domain relay map on the same dashboard page (configures sender_dependent_relayhost_maps under the hood) - see Multi-Domain Setup below.

Multi-Domain Setup¶

For setups with multiple domains and different Exchange servers (e.g. BALZ Informatik AG with 26 domains), use MX records for per-domain routing:

domain1.com    MX 10  exchange1.domain1.com
domain1.com    MX 20  HINGateway.domain1.com

domain2.com    MX 10  exchange2.domain2.com
domain2.com    MX 20  HINGateway.domain2.com

Each domain's MX records tell HIN Gateway where to deliver processed mail for that specific domain.

Verify HIN Gateway Configuration¶

After setup, verify the Stalwart configuration:

Check relay configuration¶

docker logs stargate-stalwart --tail 50 | grep -i relay

Check mail queue (should be empty when everything is working)¶

docker exec stargate-stalwart stalwart-cli -u http://localhost:8080 queue list

Send a test email and check logs¶

docker logs stargate-stalwart --tail 50

Troubleshooting¶

Mail not leaving Exchange Online¶

Verify the transport rule is enabled (it is created in a disabled state)
Check the rule conditions - it should apply to recipients "Outside the organization"
Verify the outbound connector validation passed
Check Exchange message trace in the Admin Center for delivery status

Mail loops (duplicate messages)¶

Ensure the transport rule has the exception for the HIN Gateway IP address
Without this exception, mail from HIN Gateway arriving at Exchange gets redirected back to HIN Gateway

HIN Gateway not accepting mail from Exchange¶

Check port 25 is open on the HIN Gateway server's firewall
Verify SPF record includes the HIN Gateway IP
Check Stalwart logs: docker logs stargate-stalwart

Exchange Online rejecting mail from HIN Gateway¶

Verify the inbound connector is configured with the correct HIN Gateway IP
Check that the HIN Gateway IP hasn't changed
Verify the connector is enabled (Status: On)

TLS Certificate Errors¶

HIN Gateway uses opportunistic TLS with a self-signed certificate. The outbound connector in Exchange should be configured to accept "Any digital certificate, including self-signed certificates". If you see TLS-related errors:

Verify the outbound connector security setting allows self-signed certificates
For on-premises Exchange, ensure the Send connector does not require TLS (-RequireTLS $false)

Validation fails during connector creation¶

The outbound connector validation requires:

HIN Gateway server is running and accepting connections on port 25
The validation email address is valid for your domain
Network path between Exchange Online and HIN Gateway is open (no firewall blocking)

Quick Reference¶

Component	Exchange Online Location	Purpose
Outbound Connector	Admin Center → Mail flow → Connectors	Route outbound mail to HIN Gateway
Inbound Connector	Admin Center → Mail flow → Connectors	Accept mail from HIN Gateway
Transport Rule	Admin Center → Mail flow → Rules	Trigger outbound connector for external recipients
Send to MX Connector	Admin Center → Mail flow → Connectors	Deliver mail returning from HIN Gateway to the recipient's MX
outgoing_to_mx Rule	Admin Center → Mail flow → Rules	Route mail returning from HIN Gateway to the Send to MX connector

DNS Record	Example	Purpose
A	`mail IN A <HIN Gateway_IP>`	Point hostname to HIN Gateway
MX (HIN Gateway)	`@ IN MX 15 mail.<YOUR_DOMAIN>.`	Inbound mail hits HIN Gateway first
MX (Exchange)	`@ IN MX 20 <DOMAIN>.mail.protection.outlook.com.`	Fallback / delivery target
SPF	`ip4:<HIN Gateway_IP>` and `ip4:<HIN_SEALER_IP>` added to existing TXT record	Authorize HIN Gateway and HIN sealer to send mail

For the full DNS setup (including PTR, DMARC, DKIM, and multi-domain), see the DNS Setup Guide.