Manual configuration of Exchange Online connectors with PowerShell

Problem:

You would like to know how to use PowerShell to manually create Exchange Online outbound and inbound connectors and the CodeTwo Exchange transport rule for CodeTwo Email Signatures for Office 365.

Solution:

This is an alternative method to create the connectors and the mail flow rule that can be helpful if:

• the automatic (recommended) or the manual UI-based methods do not work for you, e.g. because certain Microsoft services are down,
• you prefer to create connectors yourself and you’re familiar with PowerShell, so it’s a quicker method for you.

To succeed, it’s important that you follow the order of the configuration outlined below. In short, you need to configure:

• Exchange Online outbound connector that will route your emails through CodeTwo to get signatures,
• Exchange Online inbound connector that will accept emails with CodeTwo signatures back to your tenant for final delivery,
• Exchange Online transport rule that will filter emails that should be processed by CodeTwo service. The rule also helps avoid loops and duplicate signatures.

Steps to complete

Before you start creating anything, you need to complete these preliminary steps:

1. In CodeTwo Admin Panel, click Exchange Online connectors in the left-hand navigation menu and select the I manage my connectors manually option (Fig. 1.).

Fig. 1. Choosing to configure connectors manually.

2. Run Windows PowerShell console as an admin and connect to your tenant’s Exchange Online. To learn how to do it, refer to this article.

   Important

   To successfully connect to Exchange Online after July 1st, 2023, you need to update to Exchange Online Management PowerShell V3 module. Learn more

Once you’ve successfully connected to Exchange Online, you can proceed with the steps below.

Create Exchange Online outbound connector

1. Copy the following cmdlet and paste it into the Windows PowerShell console:

   New-OutboundConnector -Name "CodeTwo Outbound Connector" -ConnectorType OnPremises -CloudServicesMailEnabled $True -Enabled $True -SmartHosts <your unique subdomain name>.smtp.codetwo.online -IsTransportRuleScoped $True -TlsSettings DomainValidation -TlsDomain *.codetwo.com -UseMXRecord $False -RouteAllMessagesViaOnPremises $False

   Replace <your unique subdomain name> with your actual unique subdomain name that is a part of the *.smtp.codetwo.online domain added to your tenant during the provisioning of our software. To learn how to find the domain (and hence the subdomain), follow the instructions from this article.

   Important

   To avoid any configuration issues in the future, for example if you decide to reconfigure connectors automatically using the wizard, make sure not to change the default name of the connector (CodeTwo Outbound Connector), provided in the cmdlet after the −Name parameter.

2. Execute the cmdlet by pressing Enter – a new outbound connector will be created.

Create the inbound connector

1. Copy the following cmdlet and paste it into the console:

   New-InboundConnector -Name "CodeTwo Inbound Connector 2.0" -SenderDomains * -ConnectorType OnPremises -CloudServicesMailEnabled $True -RestrictDomainsToCertificate $False -RequireTls $True -TlsSenderCertificateName <your unique subdomain name>.smtp.codetwo.online -Enabled $True

   Again, replace <your unique subdomain name> with your actual unique subdomain name, as described here.

   Important

   To avoid any configuration issues in the future, for example if you decide to reconfigure connectors automatically using the wizard, make sure not to change the default name of the connector (CodeTwo Inbound Connector 2.0), provided in the cmdlet after the −Name parameter.

2. Execute the cmdlet by pressing Enter – a new inbound connector will be created.

Create the transport rule

1. Copy the following cmdlet and paste it into the console:

   New-TransportRule -Name "CodeTwo Exchange transport rule" -Mode Enforce -RuleErrorAction Defer -SenderAddressLocation HeaderOrEnvelope -Priority 0 -FromScope InOrganization -ExceptIfHeaderMatchesMessageHeader X-CodeTwoProcessed -ExceptIfHeaderMatchesPatterns $true -ExceptIfFromAddressMatchesPatterns "<>" -ExceptIfMessageTypeMatches Calendaring -RouteMessageOutboundConnector "CodeTwo Outbound Connector"

   Make sure that the outbound connector name (highlighted in red) is exactly the same as the one used in the cmdlet to create the outbound connector.

   Important - limiting the scope of users

   If you execute the cmdlet code shown above, you’ll configure our software to add signatures to emails send by all users in your tenant. If you want to limit the scope of the users who will get CodeTwo signatures to a selected group, add the following code at the end of the cmdlet, remembering to add a single space before:

   -FromMemberOf <group name in Microsoft 365>

   where <group name in Microsoft 365> should be replaced with the actual name of a group with no spaces included, e.g. SalesandMarketing.

2. Execute the cmdlet by pressing Enter – a new transport rule will be created.

Check the configuration

Now, you can run the following 3 cmdlets to make sure that Exchange Online connectors and the transport rule have been created successfully in your tenant:

Get-OutboundConnector
Get-InboundConnector
Get-TransportRule

If the newly created items are listed in the Windows PowerShell console after running the cmdlets (as shown in Fig. 2.), your configuration is OK.

Fig. 2. Checking if the connectors and the rule have been created successfully.

In such a case, disconnect from Exchange Online by using the following cmdlet:

Disconnect-ExchangeOnline

Once you’ve completed all the steps, you can now access the signature management app to start managing your email signatures. Learn more