Knowledge Base

How to route internal Office 365 messages through an on-premises mail server


In your hybrid environment with Centralized Mail Transport, internal emails sent between Office 365 (cloud) mailboxes are not routed through your on-premises Exchange server. As a result, CodeTwo software is not able to process these emails (e.g. add email signatures).


The software from the CodeTwo Exchange Rules family can only process emails that travel through on-premises (local) Exchange Server. By default, the Centralized Mail Transport (CMT) feature does not apply to messages sent internally between cloud mailboxes (that is, mailboxes in Office 365 / Exchange Online) - such messages are not routed through the on-premises part of your organization. If you want the CodeTwo software to process internal emails sent from one Office 365 mailbox to another, you need to reconfigure the mail flow in your Office 365 tenant (Exchange Online) so that these emails pass through your on-premises mail server. Such reconfiguration requires:

  1. Creating an Exchange Online connector with the same settings as the outbound hybrid connector responsible for delivering messages to your on-premises server, but that can only be triggered by a transport rule. See guidelines
  2. Creating a transport rule that uses the newly created connector and applies only to messages sent by your Office 365 mailboxes. See guidelines


Before you continue, make sure you understand the purpose of this article and that your environment meets all CodeTwo software requirements. Learn more in the manual of your CodeTwo product: CodeTwo Exchange Rules Pro | CodeTwo Exchange Rules

The solution described in this article applies only to objects that are synchronized between your Office 365 and on-premises Exchange - if you have any Office 365 objects that exist only in the cloud (the on-prem part of your environment does not have any references to these objects), they need to be excluded from the transport rule. Read on for more details.

Creating an outbound connector based on the existing outbound hybrid connector

Exchange Online connectors allow you to choose which messages are routed through them (Fig. 1.). Two routing methods are available: you can specify the scope of messages directly in the connector setup (so the connector controls the scope autonomously) or you can set the connector to be used only when a transport rule redirects messages to this connector (this is known as conditional mail routing). A single connector can only use one routing method at a time.

The message routing options in the connector configuration.
Fig. 1. The message routing options in the connector configuration.

By default, your outbound hybrid connector is configured to automatically control which messages are sent to the on-premises part of the environment. You need to be able to control your hybrid outbound connector via a transport rule, without affecting the current (default) hybrid configuration. The safest way to achieve that is to create a new Exchange Online connector by copying the configuration of the existing outbound hybrid connector, and setting this new connector to be triggered by a transport rule. To do so, please follow these steps:

  1. Log in to your Office 365 tenant and open the Microsoft 365 admin center (Office 365 admin center).
  2. Use the menu to navigate to Admin centers > Exchange. This opens the Exchange admin center.
  3. Go to Mail flowConnectors.
  4. Find your outbound hybrid connector. You can recognize it by its mail flow scenario: it is set to transfer messages FROM Office 365 and TO Your organization's email server. Also, its name usually begins with: Outbound to <your GUID here>.
  5. Select this connector, carefully note down all the configuration information presented in the right pane, and close the pane.
  6. Make sure the connector can be validated.


    If your connector cannot be validated, this is caused by issues related to your environment. Do not proceed further until you solve all the problems and validate the connector. Otherwise, your messages may not be delivered correctly.

  7. Once your connector is successfully validated, you can create its clone which will be controlled via a transport rule. In this way you will be able to decide which messages are supposed to reach the on-premises part of the environment, without affecting the default hybrid configuration.
  8. To create a new connector, click the Add a connector button.
  9. On the first page of the wizard, select the following mail flow scenario: Connection from: Office 365, Connectionto: Your organization's email server (Fig.2.). Click Next.

Creating a clone of the default hybrid outbound connector.
Fig. 2. Creating a clone of the default hybrid outbound connector.

  1. Provide a name for the connector (e.g. OnPremisesManualForward), leave all the other settings (checkboxes) as they are, and proceed to the next step.
  2. In the next step, you need to specify when you want to use your connector. Make sure to select Only when I have a transport rule set up that redirects messages to this connector (see Fig. 1.).
  3. Complete the wizard using the same settings as those in your default outbound hybrid connector (you should have noted down all the required information, as mentioned earlier).
  4. Validate your connector and make sure it works correctly.


    If your connector is not validated successfully, this is caused by issues related to your environment. Do not proceed further until you solve all the problems and complete the validation. Otherwise, your emails may not be delivered correctly.

After you successfully verify your new connector, you can proceed and create a transport rule that will route your emails to this connector.

Creating a transport rule to forward messages sent by Office 365 mailboxes to the new connector

If you have completed creating and validating the new (cloned) outbound hybrid connector, you need to create a transport rule that will forward specific messages (in this case: messages sent from mailboxes in your Office 365) to your on-premises mail server.


The transport rule you are about to create is applicable only to objects (such as user mailboxes) that are synchronized with the on-premises part of your environment. If you have any Office 365 objects that exist only in the cloud, and the on-premises mail server does not have any references to these objects, they need to be excluded from the transport rule. We strongly recommend creating a separate distribution group for these cloud-only objects before you proceed, as this allows you to conveniently manage them when configuring the transport rule.

  • If you do not exclude the cloud-only objects from the transport rule (exception #3 in the example below), messages sent to these objects will get stuck on the on-premises server because these objects will not be recognized. Your local Exchange server will neither be able to deliver messages to these objects nor to generate an NDR message due to the following error:
    550 5.1.10 RESOLVER.ADR.RecipientNotFound; Recipient not found by SMTP address lookup
  • Emails sent by the cloud-only objects can be delivered and processed by the CodeTwo software (because CMT routes them through the on-premises server), but the on-premises mail server is not able to pull any sender information from AD into email signatures. That is why it's also recommended to exclude these emails from the transport rule (see exception #2 in the example provided).

If you need signatures for your cloud-only Office 365 objects, consider using CodeTwo Email Signatures for Office 365 just for them.

To avoid situations in which a message keeps coming back and forth between the on-premises environment and Office 365 (it is stuck in an endless routing loop), the new transport rule will add a custom message header to messages sent by Office 365 mailboxes.

To create the transport rule that redirects messages to the newly created connector, you need to:

  1. Open the Exchange admin center again and go to the Mail flow > Rules.
  2. Click the Add (+) button. From the drop-down menu, select Create a new rule.
  3. Name the rule and click More options to expand all the options.
  4. In the Apply this rule if section, configure the following condition: The sender... > is external/internaland choose Inside the organization.
  5. In the Do the following section, add the following actions (keep the same order):
    • Action #1: Modify the message properties > set a message header. Name the header as you want (e.g. X-OnPremisesManualForward) and set the value to true.
    • Action #2: Redirect the message to... > the following connector and choose your cloned hybrid outbound connector.
  6. In the Except if section, add the following exceptions:
    • Exception #1: A message header... > includes any of these words. You need to use the same header name as in action #1 (here: X-OnPremisesManualForward) and specify the following phrase: true. This exception prevents against message routing loops.
    • ​Exception #2: The sender... > is a member of this group and select the distribution group containing the cloud-only objects (Office 365 objects that are not synchronized with your on-premises Exchange server).
    • ​Exception #3: The recipient... > is a member of this group and select your distribution group with the cloud-only objects (Office 365 objects that are not synchronized with your on-premises Exchange server).
  7. Scroll down and select the Defer the message if rule processing doesn't complete checkbox to make sure the rule will not be skipped in case of any mail flow issues.
  8. The complete transport rule should look similar to the one shown in Fig. 3. Click the Save button to finish the configuration.

Fig. 3. An example configuration of the new transport rule.

From now on, messages sent between your Office 365 users should be routed through the on-premises environment without causing any delivery issues, and the CodeTwo software should be able to process them.

Was this information useful?