Update-Recipient

 

Applies to: Exchange Server 2016

This cmdlet is available only in on-premises Exchange Server 2016.

Use the Update-Recipient cmdlet to add Microsoft Exchange attributes to recipient objects created by the global address list (GAL) synchronization management agent in Microsoft Forefront Identity Manager (FIM) 2010. The recipient objects you modify using this cmdlet must reside on a server running Microsoft Exchange Server 2010 or later.

For information about the parameter sets in the Syntax section below, see Syntax.

Update-Recipient -Identity <RecipientIdParameter> [-Confirm [<SwitchParameter>]] [-Credential <PSCredential>] [-DomainController <Fqdn>] [-WhatIf [<SwitchParameter>]]

This example adds Exchange attributes to the mail contact that represents John Smith's mailbox.

Update-Recipient -Identity "John Smith"

This example updates all contacts in a specific organizational unit (OU). This example assumes that recipients are synchronized between two forests, contoso.com and fabrikam.com, and all the synchronized recipients from the fabrikam.com domain are stored in a specific OU called fabrikam.com Users in the contoso.com domain.

Get-MailContact -OrganizationalUnit "contoso.com/fabrikam.com Users" | Update-Recipient

Because of mergers, acquisitions, or legal requirements, customers may need to deploy Exchange in a multiple Exchange forest topology. These deployments require the synchronization of recipient objects across disparate Active Directory forests.

Microsoft provides the GAL synchronization management agent for synchronizing recipient objects. The version of the GAL synchronization management agent included in Microsoft Identity Integration Server (MIIS) 2003 was designed to work with Exchange Server 2003 and relied on the Recipient Update Service. Because the Recipient Update Service is a deprecated feature and is no longer required, the new GAL synchronization management agent included in FIM 2010 is designed to function without the Recipient Update Service.

As part of the synchronization process, the FIM 2010 GAL synchronization management agent creates recipient objects in both Active Directory forests. After the recipients are created, the management agent uses the Update-Recipient cmdlet to add the attributes required by Microsoft Exchange to complete the provisioning of these recipients.

In Exchange, before you can run the Update-Recipient cmdlet to convert an Active Directory user object into an Exchange mailbox, you must stamp the user object with the following three mandatory Exchange attributes:

  • homeMDB

  • mailNickname

  • msExchHomeServerName

noteNote:
If you're using MIIS 2003, you must run various cmdlets to complete the provisioning process of the mail contacts created by the GAL synchronization management agent. The Update-Recipient cmdlet provides an alternate and more efficient method to do this. You can run the Update-Recipient cmdlet against the recipient objects created by the MIIS 2003 GAL synchronization management agent to complete the provisioning process.

You need to be assigned permissions before you can run this cmdlet. Although all parameters for this cmdlet are listed in this topic, you may not have access to some parameters if they're not included in the permissions assigned to you. To see what permissions you need, see the "Recipient Provisioning Permissions" section in the Recipients Permissions topic.

 

Parameter Required Type Description

Identity

Required

Microsoft.Exchange.Configuration.Tasks.RecipientIdParameter

The Identity parameter specifies the recipient.

This parameter accepts the following values:

  • Alias

    Example: JPhillips

  • Canonical DN

    Example: Atlanta.Corp.Contoso.Com/Users/JPhillips

  • Display Name

    Example: Jeff Phillips

  • Distinguished Name (DN)

    Example: CN=JPhillips,CN=Users,DC=Atlanta,DC=Corp,DC=contoso,DC=com

  • Domain\Account

    Example: Atlanta\JPhillips

  • GUID

    Example: fb456636-fe7d-4d58-9d15-5af57d0354c2

  • Immutable ID

    Example: fb456636-fe7d-4d58-9d15-5af57d0354c2@contoso.com

  • Legacy Exchange DN

    Example: /o=Contoso/ou=AdministrativeGroup/cn=Recipients/cn=JPhillips

  • SMTP Address

    Example: Jeff.Phillips@contoso.com

  • User Principal Name

    Example: JPhillips@contoso.com

Confirm

Optional

System.Management.Automation.SwitchParameter

The Confirm switch specifies whether to show or hide the confirmation prompt. How this switch affects the cmdlet depends on if the cmdlet requires confirmation before proceeding.

  • Destructive cmdlets (for example, Remove-* cmdlets) have a built-in pause that forces you to acknowledge the command before proceeding. For these cmdlets, you can skip the confirmation prompt by using this exact syntax: -Confirm:$false.

  • Most other cmdlets (for example, New-* and Set-* cmdlets) don't have a built-in pause. For these cmdlets, specifying the Confirm switch without a value introduces a pause that forces you acknowledge the command before proceeding.

Credential

Optional

System.Management.Automation.PSCredential

The Credential parameter specifies the user name and password to use to access Active Directory.

This parameter requires you to create a credentials object by using the Get-Credential cmdlet. For more information, see Get-Credential.

DomainController

Optional

Microsoft.Exchange.Data.Fqdn

The DomainController parameter specifies the domain controller that's used by this cmdlet to read data from or write data to Active Directory. You identify the domain controller by its fully qualified domain name (FQDN). For example, dc01.contoso.com.

WhatIf

Optional

System.Management.Automation.SwitchParameter

The WhatIf switch simulates the actions of the command. You can use this switch to view the changes that would occur without actually applying those changes. You don't need to specify a value with this switch.

To see the input types that this cmdlet accepts, see Cmdlet Input and Output Types. If the Input Type field for a cmdlet is blank, the cmdlet doesn’t accept input data.

To see the return types, which are also known as output types, that this cmdlet accepts, see Cmdlet Input and Output Types. If the Output Type field is blank, the cmdlet doesn’t return data.

 
Show: