How to Sync Primary SMTP Address Changes from Source to Target in GALsync

Purpose

A user's primary SMTP address is changed in the source environment, and the corresponding contact in the partner or target environment keeps the old address. Worse, once GALsync does process the change, the old contact is deleted and a new one created — which breaks Outlook's cached entries and produces non-delivery reports. This article explains why, and gives the documented procedure that makes the change synchronize cleanly instead.

Understanding primary SMTP address synchronization

GALsync matches synchronized objects by primary SMTP address. That single fact explains the whole behaviour. When the primary SMTP address of a user, contact or group changes at the source, GALsync can no longer find the contact it previously created in the target environment, because the value it matches on no longer exists. It therefore does the only thing it can: it deletes the old contact and creates a new one carrying the new address.

The visible consequence is not the deletion itself but what follows it. The recreated contact has a new legacyExchangeDN. Outlook clients in the partner environment hold the old legacyExchangeDN in their nickname cache and autocomplete list, so mail sent to the cached entry is addressed to an object that no longer exists and generates a non-delivery report. Users experience this as "the address changed and now mail bounces", and it persists until each client's cache is cleared or expires.

The documented procedure

NETsec documents a way to make GALsync match the existing contact instead of replacing it: record the old primary SMTP address in a custom attribute on the source object, prefixed with galsync:, before or at the time the address is changed.

• On-premises source: use one of extensionAttribute1 to extensionAttribute15.
• Exchange Online source: use one of customAttribute1 to customAttribute15.

The value takes the form of the prefix followed by the old address, for example:

galsync:joe.dole@example.com

With that value present, GALsync finds the existing contact in the target environment using the old address, updates its primary SMTP address in place, and leaves the legacyExchangeDN alone. No deletion, no recreation, and no cached-entry breakage.

To set the attribute on an Exchange Online source object:

Set-Mailbox -Identity <user> -CustomAttribute1 'galsync:<old-primary-smtp>'

# confirm
Get-Mailbox -Identity <user> | Format-List PrimarySmtpAddress, CustomAttribute1

And on an on-premises source object:

Set-ADUser -Identity <user> -Replace @{ extensionAttribute1 = 'galsync:<old-primary-smtp>' }

# confirm
Get-ADUser -Identity <user> -Properties extensionAttribute1, mail |
    Format-List Name, mail, extensionAttribute1

Sequence and prerequisites

1. Record the old address first. Set the custom attribute before the next export runs. If an export has already carried the new address without the attribute present, the deletion and recreation will happen on the following import.
2. Use a custom attribute that is not already in use. These attributes are commonly used for licensing, addressing policies and filtering; pick one that is free across the objects you are changing.
3. Check that the attribute is within the export scope. If an object filter excludes the object, none of this applies to it.
4. Run export and import in order and confirm the result on a small number of objects before applying the change at scale.

When the update fails with a proxy address conflict

A distinct failure produces a similar symptom — the target contact never updates — but has a different cause. The import log shows an error of this shape:

The proxy address "SMTP:<address>" is already being used by the proxy addresses
or LegacyExchangeDN of "<object-guid>". Please choose another proxy address.

The address being imported already exists somewhere in the target directory — typically on a mailbox, a mail-user, or a leftover contact from an earlier migration. Exchange will not allow the same proxy address on two objects, so the import fails for that object and it silently stays on its old values.

To identify the conflicting object in the target environment:

Get-Recipient -Filter "EmailAddresses -eq 'smtp:<address>'" |
    Format-List Name, RecipientTypeDetails, PrimarySmtpAddress, Guid

Resolve the conflict at the object that holds the address, not at GALsync. That usually means removing the stale proxy address from a migration leftover, or excluding the source-domain objects from the import with an object filter so the two never compete for the same address.

Import policy options worth knowing

Several options on the Directory Settings → Email Addresses tab of an import policy affect how addresses are handled. Two carry important limitations:

• Add suffix to MailNickname extends the MailNickname to prevent duplicate values, which matters because the legacyExchangeDN is derived from the Exchange administrative group and the MailNickname. It applies only when a new contact is created, never to objects already created, and it is on-premises only — which is why it will not appear in the policy if the target is Exchange Online. The MailNickname is limited to 64 characters, from the set a-z A-Z 0-9 . _ - +.
• Modify mail address with domain is also on-premises only. It does not rewrite primary SMTP addresses to a new domain. It takes the first address matching the domain filter you supply from the source object's proxyAddresses and sets that as the mail attribute on the imported contact — so that a mailbox whose primary address is at one domain can be imported with its secondary address at another domain as the mail attribute.
• Retain targetAddress of users and contacts keeps the source object's targetAddress rather than stamping it with the source primary SMTP address, which is the default.

These options change how addresses are written and are worth testing on a small import policy before applying them to a production one.

Verifying the change

1. In the target environment, confirm the contact carries the new primary SMTP address and check its creation timestamp — an unchanged timestamp confirms the object was matched and updated rather than recreated.
2. Confirm the legacyExchangeDN is unchanged if you have the previous value recorded.
3. Send a test message from the target environment to the updated contact.
4. If users still see non-delivery reports after a successful update, the cause is the local Outlook nickname cache holding the old entry; removing the stale autocomplete entry resolves it per client.

References

• GALsync 8.7 Manual p.231 — How to change the primary SMTP address of users in the source environment, which are synced to partners with GALsync.
• GALsync 8.7 Manual p.192 — the galsync: custom attribute mark, and Modify mail address with domain.
• GALsync 8.7 Manual p.194 — Add suffix to MailNickname and Retain targetAddress of users and contacts.
• The current GALsync manual is published by NETsec at netsec.de.