Scope: hybrid Exchange (on-premises Exchange 2016/2019 + Exchange Online + Microsoft Entra Connect), where on-premises applications send mail through an on-prem relay.
Why this matters
- Many on-premises apps (issue trackers, wikis, build servers, monitoring tools) send notifications to an on-premises SMTP relay, not straight to Exchange Online.
- The relay decides where to deliver by looking up the recipient in on-prem Active Directory / Exchange.
- If the user's on-prem object is not a mail-enabled recipient, the relay has no route, even though the user has a working cloud mailbox.
- Result: the user gets normal mail from the internet and other cloud users, but nothing from internal on-prem apps.
How hybrid routing works for a cloud mailbox
- Every cloud mailbox user in a hybrid org should exist on-prem as a RemoteUserMailbox.
- That object carries a targetAddress (the remote routing address, usually
user@tenant.mail.onmicrosoft.com).
- On-prem transport sees the RemoteUserMailbox, rewrites delivery to the targetAddress, and sends it over the hybrid connector to Exchange Online.
- If the object is a plain AD user, transport tries to find a local mailbox database, finds none, and defers the message.
| On-prem object state | What on-prem transport does | Outcome |
| RemoteUserMailbox with targetAddress | Routes to the onmicrosoft address | Delivered to the cloud mailbox |
| Plain user, no Exchange attributes | Looks for a local mailbox database | Deferred: 420 4.2.0 Recipient deferred because there is no Mdb |
| MailUser pointing at a wrong or stale address | Routes to that address | Lost, bounced or looped |
When the gap appears
- Account type conversions (contractor to employee, re-hire, rejoin) where a new AD account is created and the mailbox is provisioned in the cloud directly.
- Mailboxes created in Exchange Online first, then matched to an on-prem account later.
- Manual clean-up of Exchange attributes during offboarding, then re-use of the account.
- Provisioning scripts that set
mail and proxyAddresses but never call an Exchange cmdlet.
Key attributes to know
| AD attribute | Healthy value for a cloud mailbox user | Meaning |
| msExchRecipientTypeDetails | 2147483648 | RemoteUserMailbox |
| msExchRemoteRecipientType | 1 (ProvisionMailbox) or 4 (Migrated) | How the cloud mailbox came to exist |
| targetAddress | SMTP:user@tenant.mail.onmicrosoft.com | Where on-prem transport forwards mail |
| msExchMailboxGuid (ExchangeGuid) | Same GUID as the Exchange Online mailbox | Links the on-prem object to the existing cloud mailbox |
| proxyAddresses | SMTP:primary plus aliases | Must match the cloud primary address |
Recognising the pattern
- Exchange Online message trace shows zero messages from the on-prem app sender to the user, while the same sender delivers to everyone else.
- The user's cloud mailbox receives other mail normally; no inbox rules or blocked senders.
Get-ADUser shows empty msExchRecipientTypeDetails and targetAddress.
- On-prem tracking logs or queues show
DEFER with "no Mdb" for that recipient.
- Important: Exchange Online trace cannot see this, because the mail never leaves on-prem.
The fix
- Step 1: read the cloud mailbox ExchangeGuid from Exchange Online.
- Step 2: on on-prem Exchange, run
Enable-RemoteMailbox with the onmicrosoft routing address.
- Step 3: run
Set-RemoteMailbox -ExchangeGuid so the on-prem object points at the existing cloud mailbox.
- Step 4: confirm the primary SMTP address did not change (email address policies can add or reorder addresses).
- Step 5: let Entra Connect sync (or run a delta sync), retry deferred queues, and send a test notification.
Things to watch
- Enable-RemoteMailbox and Set-RemoteMailbox exist only in on-premises Exchange. They are not in the Exchange Online module.
- Running both modules in one window causes cmdlet name clashes. Use
Connect-ExchangeOnline -Prefix Cloud or separate windows.
- Skipping the ExchangeGuid step can lead to sync trying to provision a second mailbox or a mailbox conflict.
- An email address policy may stamp extra aliases from on-prem-only domains. Unverified domains are dropped by the cloud during sync, which is harmless.
- In an imported remote session, piping
Get-TransportService into Get-MessageTrackingLog or Get-Queue does not bind. Loop with -Server instead.
Get-MessageTraceV2 -Subject requires -SubjectFilterType (Contains, StartsWith or EndsWith).
- Routing works as soon as AD replication and the transport recipient cache catch up; the sync mainly keeps the cloud object consistent.
- Always export the current attributes before changing them.
My thoughts
- This is a process gap, not a product bug. The joiner/converter workflow creates the identity and the cloud mailbox but skips the on-prem Exchange step.
- The fix belongs in the account conversion runbook: any new or converted account that gets a cloud mailbox should be created with
New-RemoteMailbox or Enable-RemoteMailbox, never by setting attributes by hand.
- A scheduled check (section 9 of the script) that lists users with a primary SMTP but no recipient type catches these before users notice.
- When an on-prem app "stops emailing one person", check on-prem routing first. A clean Exchange Online trace often means the problem is upstream, not that mail flow is healthy.
- As long as on-prem apps relay through Exchange, the on-prem recipient objects matter, even when every mailbox is in the cloud.
References
Full script
- Plain variables at the top, no parameter block, so it can be run line by line.
- Sample names (contoso) only. Replace them with your own values.
# =====================================================================
# Hybrid RemoteMailbox check and fix for a user whose mailbox is in
# Exchange Online but whose on-premises AD account is not mail-enabled.
# Run line by line or section by section. Replace the sample values first.
# Requires: ActiveDirectory module, ExchangeOnlineManagement module,
# network access to an on-premises Exchange 2016/2019 server.
# =====================================================================
# ---------- Variables (edit these) ----------
$samAccount = 'jdoe1' # On-prem sAMAccountName of the user
$primarySmtp = 'John.Doe1@contoso.com' # Primary SMTP address used in Exchange Online
$routingAddr = 'John.Doe1@contoso.mail.onmicrosoft.com' # Tenant routing (onmicrosoft) address
$adminUpn = 'admin@contoso.com' # Account used to connect to Exchange Online
$exchServer = 'exch01.contoso.local' # On-prem Exchange server FQDN
$appSender = 'noreply-app@contoso.com' # Sender address of the on-prem application
$backupPath = "$env:USERPROFILE\$samAccount" + '_before.csv'
# ---------- 1. Inspect the on-prem AD object ----------
# Empty msExchRecipientTypeDetails and targetAddress means the account
# is not mail-enabled, so on-prem Exchange cannot route mail for it.
$adUser = Get-ADUser -Identity $samAccount -Properties mail, proxyAddresses, targetAddress, msExchRecipientTypeDetails, msExchRemoteRecipientType
$adUser | Format-List SamAccountName, UserPrincipalName, mail, targetAddress, msExchRecipientTypeDetails, msExchRemoteRecipientType, proxyAddresses
if ($adUser.msExchRecipientTypeDetails -eq 2147483648) {
Write-Host 'User is already a RemoteUserMailbox. No fix needed.' -ForegroundColor Green
} else {
Write-Host 'User is NOT a RemoteUserMailbox. Continue with the fix.' -ForegroundColor Yellow
}
# ---------- 2. Back up current attributes (rollback reference) ----------
$adUser | Select-Object SamAccountName, mail, targetAddress,
@{n='proxyAddresses';e={$_.proxyAddresses -join ';'}} |
Export-Csv -Path $backupPath -NoTypeInformation
Write-Host "Backup saved to $backupPath"
# ---------- 3. Get the ExchangeGuid of the cloud mailbox ----------
# -Prefix Cloud keeps Exchange Online cmdlets separate from on-prem ones
# (Get-CloudMailbox instead of Get-Mailbox) in the same window.
Connect-ExchangeOnline -UserPrincipalName $adminUpn -Prefix Cloud -ShowBanner:$false
$cloudMbx = Get-CloudMailbox -Identity $primarySmtp
$exchangeGuid = $cloudMbx.ExchangeGuid
$cloudMbx | Format-List DisplayName, PrimarySmtpAddress, ExchangeGuid
# ---------- 4. Connect to on-prem Exchange ----------
$session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri "http://$exchServer/PowerShell/" -Authentication Kerberos
Import-PSSession $session -DisableNameChecking -AllowClobber | Out-Null
# ---------- 5. Mail-enable as RemoteMailbox and stamp the ExchangeGuid ----------
# Enable-RemoteMailbox sets targetAddress so the relay can route to the cloud.
# Matching ExchangeGuid ties the on-prem object to the existing cloud mailbox
# instead of letting sync treat it as a new mailbox to provision.
Enable-RemoteMailbox -Identity $samAccount -RemoteRoutingAddress $routingAddr
Set-RemoteMailbox -Identity $samAccount -ExchangeGuid $exchangeGuid
# ---------- 6. Verify ----------
$remote = Get-RemoteMailbox -Identity $samAccount
$remote | Format-List Name, PrimarySmtpAddress, RemoteRoutingAddress, ExchangeGuid, EmailAddressPolicyEnabled, EmailAddresses
# An email address policy can change the primary address. Put it back if needed.
if ($remote.PrimarySmtpAddress.ToString() -ne $primarySmtp) {
Write-Host 'Primary SMTP changed by policy. Restoring it.' -ForegroundColor Yellow
Set-RemoteMailbox -Identity $samAccount -PrimarySmtpAddress $primarySmtp -EmailAddressPolicyEnabled $false
} else {
Write-Host 'Primary SMTP address unchanged.' -ForegroundColor Green
}
if ($remote.ExchangeGuid -ne $exchangeGuid) {
Write-Warning 'ExchangeGuid does not match the cloud mailbox. Do not sync until fixed.'
} else {
Write-Host 'ExchangeGuid matches the cloud mailbox.' -ForegroundColor Green
}
# ---------- 7. Retry anything deferred for missing routing ----------
# Run per server: piping Get-TransportService into queue cmdlets
# does not bind in an imported remote session.
$transportServers = (Get-TransportService).Name
foreach ($srv in $transportServers) {
Get-Queue -Server $srv | Where-Object { $_.LastError -match 'no Mdb' } | Retry-Queue
}
# ---------- 8. Test end to end after a new application notification ----------
# On-prem: expect RECEIVE then SEND (not DEFER).
$onPremLog = foreach ($srv in $transportServers) {
Get-MessageTrackingLog -Server $srv -Recipients $primarySmtp -Start (Get-Date).AddHours(-2) -ResultSize Unlimited
}
$onPremLog | Sort-Object Timestamp | Format-Table Timestamp, ServerHostname, EventId, Sender, MessageSubject -AutoSize
# Exchange Online: expect Delivered.
Get-CloudMessageTraceV2 -SenderAddress $appSender -RecipientAddress $primarySmtp -StartDate (Get-Date).AddHours(-2) -EndDate (Get-Date) |
Format-Table Received, RecipientAddress, Status, Subject -AutoSize
# ---------- 9. Optional: find other users with the same gap ----------
# Users that have a primary SMTP in proxyAddresses but no Exchange recipient type.
Get-ADUser -Filter 'Enabled -eq $true' -Properties proxyAddresses, msExchRecipientTypeDetails |
Where-Object { ($_.proxyAddresses -cmatch '^SMTP:') -and (-not $_.msExchRecipientTypeDetails) } |
Select-Object SamAccountName, UserPrincipalName,
@{n='PrimarySmtp';e={($_.proxyAddresses -cmatch '^SMTP:') -replace '^SMTP:'}} |
Format-Table -AutoSize
# ---------- 10. Clean up ----------
Remove-PSSession $session
Disconnect-ExchangeOnline -Confirm:$false
No comments:
Post a Comment