Friday, November 20, 2026

Hybrid Exchange: Why On-Prem App Emails Miss Cloud Mailboxes, and How RemoteMailbox Fixes It

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 stateWhat on-prem transport doesOutcome
RemoteUserMailbox with targetAddressRoutes to the onmicrosoft addressDelivered to the cloud mailbox
Plain user, no Exchange attributesLooks for a local mailbox databaseDeferred: 420 4.2.0 Recipient deferred because there is no Mdb
MailUser pointing at a wrong or stale addressRoutes to that addressLost, 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 attributeHealthy value for a cloud mailbox userMeaning
msExchRecipientTypeDetails2147483648RemoteUserMailbox
msExchRemoteRecipientType1 (ProvisionMailbox) or 4 (Migrated)How the cloud mailbox came to exist
targetAddressSMTP:user@tenant.mail.onmicrosoft.comWhere on-prem transport forwards mail
msExchMailboxGuid (ExchangeGuid)Same GUID as the Exchange Online mailboxLinks the on-prem object to the existing cloud mailbox
proxyAddressesSMTP:primary plus aliasesMust 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

Featured Post

Hybrid Exchange: Why On-Prem App Emails Miss Cloud Mailboxes, and How RemoteMailbox Fixes It

Scope: hybrid Exchange (on-premises Exchange 2016/2019 + Exchange Online + Microsoft Entra Connect), where on-premises applications send m...

Popular posts