Implement cPanel with Microsoft O365 in Hybrid Environment


Feb 6, 2008
While there are several forum posts discussing Microsoft Office 365 in a Hybrid setup with cPanel, I was unable to find a definitive set of instructions that worked in our environment. The following has been tested on cPanel v100.0.9 with Microsoft O365 Exchange providing domain a specific setup in a shared cPanel environment.


Configure Exchange to work with Shared cPanel environment in Hybrid Scenario

  1. cPanel mail routing via Smarthost (Connector) is designed to be configured server-wide. In a shared environment with multiple clients utilizing the same configuration this becomes problematic.
  2. cPanel has an all-or-none policy to mail handling. Either all mail for a domain is routed locally or all mail is managed remotely. There is no native hybrid conditional setup. For mail to be received we select the “Local Mail Exchanger” option. When selected, any attempts to send messages to a remote mailbox from a local mailbox triggers a recipient error.
  1. To overcome the server-wide Smarthost limit, we setup some EXIM rules that check a smarthost configuration file for eligible domains and then apply the smarthost rule. This is not required, and it may have impact on send performance (undetermined), however it does allow transport via outlook which provide security scanning to outbound messages.
  2. To overcome the Local Mail Exchanger problem we use the “Fallback Domain” and “Alias” features in exchange. For each remote email account we configure the Alias as a forward rule in the Local environment (eg [email protected] to [email protected]).
  1. Configure your Fallback DNS
    1. From the Microsoft 365 Admin Center open the Settings > Domains area.
    2. Confirm that you already have a Fallback domain established (eg.
    3. If you would like another Fallback domain you add one by opening your existing Fallback domain and clicking "Add ‎‎ domain" on the bottom-right of the Overview tab
  2. Setup the Inbound / Outbound Connectors in O365
    1. The Inbound Connector is only necessary if you want to relay mail through Microsoft. You can skip this step if you want to have your Local accounts send mail directly.
    2. View Instructions on
  3. Setup domain specific Smarthost routing in WHM Exim Advanced Editor
    1. Open WHM > Service Configuration > Exim Configuration Manager
    2. Locate and append Section: PREROUTERS
      # Smart Host Sending - PREROUTERS
      driver = manualroute
      domains = ! +local_domains
      condition = "${if eq{${lookup{$sender_address_domain}partial-lsearch{/etc/exim_smarthosts}{$value}}}{}{false}{true}}"
      ignore_target_hosts = :
      headers_add = "${perl{mailtrapheaders}}"
      transport = sendbysmarthoststransport
      route_list = * ${extract{smtp}{${lookup{$sender_address_domain}lsearch{/etc/exim_smarthosts}}}}
    3. Locate and append Section: TRANSPORTSTART
      # Smart Host Sending - TRANSPORTSTART
      driver = smtp
      port = ${extract{port}{${lookup{$sender_address_domain}lsearch{/etc/exim_smarthosts}}}}
      hosts_require_tls = $host_address
    4. SAVE at the bottom
    5. Create the EXIM configuration file
    6. Create a file /etc/exim_smarthosts
    7. Add the following to the file and adjust as needed
      # Smarthost Definitions port=25
  4. Setup Alias Forwarders
    1. From the cPanel account for the domain, create a Forwarder for each email address that will be setup in O365 (eg [email protected] to [email protected]). When sending mail to an O365 recipient from a Local sender, this forwarder will allow the Local handler to resolve a destination, avoiding the “Invalid Recipient
      Until you've configured the MX records, Microsoft O365 will REJECT any mail sent from your Local to O365 accounts with a 550 error.
  5. Configure your MX & SPF records according to your domain rules
    1. From the Microsoft 365 Admin Center open the Settings > Domains area.
    2. Open your domain and select the DNS tab to reveal the settings.
    3. Apply and test the settings as defined.

Once the above is complete make sure to test the following conditions:
  1. Send a message from a O365 account to a Local account
  2. Send a message from a O365 account to another O365 account
  3. Send a message form a Local account to a O365 account
  4. Send a message form a Local account to another Local account
If you are using the Inbound connector and Smarthost option and having problems sending mail from Local to O365 you may find the message sitting in the mail queue. From the WHMCS interface you can open the "Mail Queue Manager" page and search for the email by sender or recipient. If found, you can open and force a delivery attempt which will provide you with a log of the connection attempt which may help identify the problem.

Common Connection Problems

  1. 110 Connection Timeout
    The Microsoft O365 connector supports TLS but not port 587. Make sure you are using Port 25. Use telnet from a command prompt to test connectivity.
    telnet 25

  2. 550 5.4.1 Recipient address rejected: Access denied.
    You may have forgotten to update the MX records. Microsoft will reject messages until the MX is pointing to their network.

These instructions can be found here as well:
Microsoft 365 Hybrid Email Environment (

This work was made possible by notes gathered from the following: