Chat now with support
Chat with Support

NOTICE! We are upgrading our support telephone services, implementing Genesys, starting the week of May 19, 2025

On Demand Migration Current - Active Directory Domain Rewrite Quick Start Guide

Will Domain Rewrite work for a source mailbox that has a contact object in the target tenant?

You cannot match a source mailbox to a contact object in the target tenant for Domain Rewrite processing. The source mailbox must be matched to a mail user, mailbox, or B2B account in the other tenant. However, if the target tenant also has contact objects representing the source mailboxes, then you may need to update them so that they do not hinder Domain Rewrite processing.

 

When enabling Domain Rewrite for mailboxes that have contacts in the other tenant, ODM will attempt to add the contacts to specific Domain Rewrite groups. This action will fail if the contacts were not created by ODM Directory Sync. This can be resolved either by deleting the pre-existing contacts or by updating an attribute on them that authorizes ODM to add them to the Domain Rewrite groups.

 

For contacts created in Active Directory, set AdminDescription = Created by DirSync

For cloud-only contacts, use PowerShell to set CustomAttribute15 = Created by DirSync

Do I need to configure a Local Directory Sync agent if my tenant is a hybrid with local Active Directory attached?

A Local Directory Sync agent is only required when working with Hybrid MailUsers (a mailuser object synced with a local active directory object). A Directory Sync agent is used to configure the mail-forwarding rule on the local AD object when working with Hybrid MailUsers. A Directory Sync agent is not required when working with Mailbox and Cloud Only Objects as mail-forwarding rules are configured via EXO PowerShell.

How are Transport Rules & Send Connectors used?

How are Transport Rules & Send Connectors used?  

Exchange Online transport rules and send connectors are used to route mail from an Microsoft 365 tenant to On Demand Migration Domain Rewrite Service. Transport Rules examine a message to determine if it should be rewritten and the connectors route the message to On Demand Migration Domain Rewrite Service. This ensures that only messages that need to be rewritten are routed to On Demand Migration Domain Rewrite Service and messages that do not are immediately sent to the recipients.

LightbulbImportant Tip: Support for the Domain Rewrite Service is limited to mail flow configurations that use Microsoft 365 for message ingress and egress. Centralized mail flow configurations that use the on-premises Exchange environment for inbound and outbound message delivery may require custom configuration with Support.

 

There are 3 categories of transport rules. The following section outlines each category and describes the naming convention used for the rules.

Sorting Rules

For outbound messages, a sorting rule examines each recipient on an SMTP message and adds an SMTP header to identify if the recipient is internal or external.

  • BT-IntegrationPro-Out-S-Internet – rule for external recipients.

  • BT-IntegrationPro-Out-S-[Guid]-[#] – rules for internal recipients in target tenant [Guid] where [#] indicates a block of SMTP domains. E.g. BT-IntegrationPro-Out-S-15d82781-e5e8-4691-a77f-0f5fb10b6482-1

From, To, CC Rules

For outbound messages, these rules determine if any of the From, To or CC addresses on an SMTP message include an internal or external recipient that should be rewritten and update the SMTP header added above appropriately.

  • BT-IntegrationPro-Out-[From/ToCc] – rules for external recipients.

  • BT-IntegrationPro-Out-[Guid]-[From/ToCc] – rules for internal recipients in target tenant [Guid]. E.g. BT-IntegrationPro-Out-15d82781-e5e8-4691-a77f-0f5fb10b6482-From.

Inbound Rules

The outbound rules ensure that Microsoft 365 routes only the messages that need to be rewritten to On Demand Migration Domain Rewrite Service. The inbound rules have two functions.

  • BT-IntegrationPro-In - rule for messages returning from On Demand Migration Domain Rewrite Service.

    After a message is rewritten, it is returned to the original tenant for delivery to external recipients.

    This rule removes the header added by the outbound rules so that a message is only processed by On Demand Migration Domain Rewrite Service once.

  • BT-IntegrationPro-In-DKIM - rule for messages returning from On Demand Migration Domain Rewrite Service.

    When an external recipient replies to an ERS user, the message is rewritten back to the original domain. After which, the message is redirected to the original tenant.

    This rule removes the secret key added to the header by the sending tenant to ensure the message was securely delivered before and after being rewritten.

How does Mail Flow work with Domain Rewrite?

LightbulbImportant Tip: Microsoft 365 Advanced Threat Protection default settings may cause issues with Domain Rewrite for inbound messages.  Please ensure that "Automatic forwarding" is set to "On" in the "Outbound spam filter policy" for your source or target tenant depending on the rewriting scenario you choose.

Rewrite with Target Address – Outbound Mail Flow

  • When a user sends an email as user@source.com, the Transport Rules in the Source Tenant check whether the message is in scope for Domain Rewrite

  • At least one external recipient in “To” or “Cc”

  • Sender and/or at least one recipient in “To” or “Cc” is Domain Rewrite Enabled

  • If the message is in scope for Domain Rewrite and there are multiple internal and external recipients, the message will be bifurcated and:

  • Copy of the message sent to external recipient will be securely redirected to the Quest Rewrite Service using the Outbound Connector in the Source Tenant.

  • Copy of the message sent to internal recipient is delivered by Exchange Online at the Source  tenant with unchanged addresses.

    LightbulbImportant Tip: Messages directed to internal recipient(s) will not be processed by Quest Rewrite Service.

     

  • When the Domain Rewrite Service receives the message from user@source.com, it processes it by rewriting @source.com to @target.com for every user that has Domain Rewrite enabled. The addresses in "From", "To", and "Cc" of the email message are rewritten for all external recipients.

  • The Domain Rewrite Service adds a new DKIM-Signature to the message and securely (via the certificate uploaded during project setup) redirects it back to the Source Tenant using the Inbound Connector.

  • Exchange Online at the Source sends the message to external recipients as if it was sent by user@target.com, and all addresses of message recipients in "To" and "Cc" that have Domain Rewrite enabled appear as @target.com for external recipients

Rewrite with Target Address – Inbound Mail Flow

  • External recipient is not aware about @source.com and replies (or creates a new email) to user@target.com

  • When the reply or a new mail arrives to the Target mail domain, the Transport Rules in the Target Tenant check whether any recipients in the “To” or “Cc” are in scope for Domain Rewrite

  • If the message is in scope for Domain Rewrite and there are multiple internal (recipients in the Target Tenant) and external recipients (recipients in the Source Tenant with Domain Rewrite enabled), the message will be bifurcated and:

  • Copy of the message sent to external recipient (recipients in the Source Tenant with Domain Rewrite enabled) will be securely redirected to the Domain Rewrite Service using the Outbound Connector in the Target Tenant

  • Copy of the message sent to internal recipient is delivered by Exchange Online at the Target tenant with unchanged addresses

  • When the Domain Rewrite Service receives the message addressed to user@target.com, it processes it by rewriting @target.com back to @source.com for every user that has Domain Rewrite enabled

  • The Domain Rewrite Service new DKIM-Signature to the message and securely (via the certificate uploaded during project setup) redirects it back to the Target Tenant using the Inbound Connector

  • Exchange Online at the Target forwards the message to the Source

  • Source recipient gets the message as if it was addressed to user@source.com

Rewrite with Source Address – Outbound Mail Flow

  • When a user sends an email as user@target.com, the Transport Rules in the Target Tenant check whether the message is in scope for Domain Rewrite

  • At least one external recipient in “To” or “Cc”

  • Sender and/or at least one recipient in “To” or “Cc” is Domain Rewrite Enabled

  • If the message is in scope for Domain Rewrite and there are multiple internal (recipients in the Target Tenant) and external recipients, the message will be bifurcated and:

  • Copy of the message sent to external recipient will be securely redirected to the Domain Rewrite Service using the Outbound Connector in the Target Tenant

  • Copy of the message sent to internal recipient is delivered by Exchange Online at the Target Tenant with unchanged addresses

  • When the Domain Rewrite Service receives the message from user@target.com, it processes it by rewriting @target.com to @source.com for every user that has Domain Rewrite enabled. The addresses in "From", "To", and "Cc" of the email message are rewritten for all external recipients

  • The Domain Rewrite Service a new DKIM-Signature to the message and securely (via the certificate uploaded during project setup) redirects it back to the Target Tenant using the Inbound Connector

  • Exchange Online at the Target sends the message to external recipients as if it was sent by user@source.com, and all addresses of message recipients in "To" and "Cc" that have Domain Rewrite enabled appear as @source.com for external recipients

Rewrite with Source Address – Inbound Mail Flow

  • External recipient is not aware about @target.com and replies (or creates a new email) to user@source.com

  • When the reply or a new mail arrives to the Source mail domain, the Transport Rules in the Source Tenant check whether any recipients in the “To” or “Cc” are in scope for Domain Rewrite

  • If the message is in scope for Domain Rewrite and there are multiple internal (recipients in the Source Tenant) and external recipients (recipients in the Target Tenant with Domain Rewrite enabled), the message will be bifurcated and:

  • Copy of the message sent to external recipient (recipients in the Target Tenant with Domain Rewrite enabled) will be securely redirected to the Domain Rewrite Service using the Outbound Connector in the Source Tenant

  • Copy of the message sent to internal recipient is delivered by Exchange Online at the Source Tenant with unchanged addresses

  • When the Domain Rewrite Service receives the message addressed to user@source.com, it processes it by rewriting @source.com back to @target.com for every user that has Domain Rewrite enabled

  • The Domain Rewrite Service a new DKIM-Signature to the message and securely (via the certificate uploaded during project setup) redirects it back to the Source Tenant using the Inbound Connector

  • Exchange Online at the Source forwards the message to the Target

  • Target recipient gets the message as if it was addressed to user@target.com

Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating