Recipient Management cmdlets introduction


Previously I posted an overview of Exchange Server 2007 recipient management at the Exchange Management console. That post only tells half the story; now we will explore recipient management through the Exchange Management Shell base on Windows PowerShell technology that is not only the underlying technology behind the GUI, but also enables bulk updates and automation that will significantly ease managing Exchange.

Exchange Server 2007 recipient management through PowerShell provides a solid management platform for use by the recipient management GUI built on top of it, as well as a flexible and powerful interface for you to use directly! The shell interface is flexible enough to be used for simple "one-liner" changes to a single user or hundreds of thousands of users. For bulk actions, or actions where you want to take some action against a filtered set of objects you will find using "one-liners" at the shell to be very effective.

Today I want to introduce the core cmdlets you can use to do recipient management through the shell interface. For each of these cmdlets I describe, you can find out more information and sample syntax by doing "help <cmdlet name>" through the Exchange Management Shell in Exchange Server 2007

Exchange Server 2007 Recipient management nouns

All cmdlets are structured as <verb> hyphen <noun>. If you think of the noun as the "type of object you will be doing some action against" and the verb as "the action you will be doing", it becomes relatively straight forward to determine which cmdlet you need to call.

We have built families of cmdlet actions around a number of object-type nouns explained in detail below.

Mailbox:

A mailbox is an AD user object that has additional Exchange mailbox properties set. These additional Exchange-related AD properties allow the user access into a "StoreMailbox" object which hosts the mailbox data within the Mailbox Database.

Historically, "mailbox" has had several possible meanings. This term was used to refer to the mailbox attributes on an AD user object, to the user object itself once it had been mailbox enabled, to the StoreMailbox data object in the mailbox database, and even to various combinations of these items. In Exchange Server 2007, "Mailbox" refers to the combination of user object with mailbox attributes in place and the StoreMailbox object in the mailbox database.

The AD properties associated with a Mailbox object are those properties that are part of the "Exchange Property Set". Some example properties are: Email addresses, HomeServer, Mailbox quotas, etc. Access to these properties is controlled by the "Exchange Recipient Administrators" delegated role, and does not rely on additional AD permissions such as Account Operator.

User:

A user is an AD user object that does not have any additional Exchange mailbox or mail properties set. User cmdlets ship with the Exchange PowerShell snapin and are not built-in cmdlets within PowerShell.

There are two reasons why User objects are exposed in Exchange PowerShell:

To allow administrators the ability to pipeline these user objects into other cmdlets (such as Enable).

To allow administrators access to those properties that are part of the "AD property set".

The AD properties associated with a User object are those properties that are part of the "AD Property Set". Some example properties are: Postal Address, Phone number, Manager, etc. Access to these properties is controlled by AD groups, such as Account Operator. Being granted "Exchange Recipient Administrators" delegated role will not give you access to these properties, you would need to be granted Account Operator or something equivalent.

Note that all Mailbox objects are also User objects, but not all User objects are also a Mailbox.

CASMailbox:

CASMailbox is a noun used to access various Client Access related properties on a mailbox object. It is not a separate object Recipient Type; it is simply used to segregate CAS-related properties into a separate view. Through these objects you will have access to the various protocol-related settings for Activesync, MAPI, OWA, etc for a mailbox.

UMMailbox:

UMMailbox is a noun used to access various Unified Messaging related properties on a mailbox object. Like CASMailbox, it is not a separate object RecipientType; it is simply used to segregate UM-related properties into a separate view. Through these objects you will have access to the various UM-related settings such as Extension, UM Mailbox Policy, Automatic Speech Recognition, etc for a mailbox.

MailUser:

A mailuser is an AD user object that has additional Exchange mail (not Mailbox) properties set. These additional Exchange-related AD properties allow the user to have mail forwarded out to some external email address. Mailuser is just like the more common MailContact type, except that it is associated with a user account security context rather than a contact.

The AD properties associated with a MailUser object are those properties that are part of the "Exchange Property Set". Some example properties are: Email addresses, External address, etc. Access to these properties is controlled by the "Exchange Recipient Administrators" delegated role, and does not rely on additional AD permissions such as Account Operator.

User:

User is already explained above in Mailbox. Since both Mailbox and MailUser are based on AD User objects, the User noun applies equally to both.

Note that all MailUser objects are also User objects, but not all User objects are also a MailUser.

MailContact:

A mailcontact is an AD contact object that has additional Exchange mail properties set. These additional Exchange-related AD properties allow the contact to have mail forwarded out to some external email address.

The AD properties associated with a MailContact object are those properties that are part of the "Exchange Property Set". Some example properties are: Email addresses, External address, etc. Access to these properties is controlled by the "Exchange Recipient Administrators" delegated role, and does not rely on additional AD permissions such as Account Operator.

Contact:

A contact is an AD contact object that does not have any additional Exchange mail properties set. Contact cmdlets ship with the Exchange PowerShell snapin and are not built-in cmdlets within PowerShell.

There are two reasons why Contact objects are exposed in Exchange:

To allow administrators the ability to pipeline these contact objects into other cmdlets (such as Enable).

To allow administrators access to those properties that are part of the "AD property set".

The AD properties associated with a Contact object are those properties that are part of the "AD Property Set". Some example properties are: Postal Address, Phone number, Manager, etc. Access to these properties is controlled by AD groups, such as Account Operator. Being granted "Exchange Recipient Administrators" delegated role will not give you access to these properties.

Note that all MailContact objects are also Contact objects, but not all Contact objects are also a MailContact.

DistributionGroup:

A distributionGroup is an AD group object that has additional Exchange mail properties set. These additional Exchange-related AD properties allow the group object to be the recipient of email which will then be distributed to all of the group members.

Note that AD has a different definition of "distributionGroup" in which the group does not have a security context, but may or may not be mail-enabled. In Exchange 2007, the use of "Distribution Group" refers to all mail-enabled groups, whether they are an AD "security group" or an AD "distribution group".

The AD properties associated with a distributionGroup object are those properties that are part of the "Exchange Property Set". Some example properties are: Email addresses, Expansion server, etc. Access to these properties is controlled by the "Exchange Recipient Administrators" delegated role, and does not rely on additional AD permissions such as Account Operator.

Group:

A group is an AD group object that does not have any additional Exchange mail properties set. Group cmdlets ship with the Exchange PowerShell snapin and are not built-in cmdlets within PowerShell.

There are two reasons why Group objects are exposed in Exchange PowerShell:

To allow administrators the ability to pipeline these group objects into other cmdlets (such as Enable).

To allow administrators access to those properties that are part of the "AD property set".

The AD properties associated with a Group object are those properties that are part of the "AD Property Set". Some example properties are: Group Type, Managed By, etc. Access to these properties is controlled by AD groups, such as Account Operator. Being granted "Exchange Recipient Administrators" delegated role will not give you access to these properties.

Note that all DistributionGroup objects are also Group objects, but not all Group objects are also a DistributionGroup.

DistributionGroupMember:

DistributionGroupMember is a noun used to access the membership of a particular distribution group. Only recipients (ie - mail-enabled or mailbox-enabled objects) can be added to the distribution group with Exchange 2007 recipient management tools.

DynamicDistributionGroup:

A DynamicDistributionGroup (DDG) is an AD object that is made available only after Exchange is installed. These objects only exist for the purpose of email, so they cannot exist as non-mail-enabled entities.

The purpose of a DynamicDistributionGroup (sometimes also referred to as Query Based Distribution Group - QBDG) is to provide dynamic group membership based on some criteria or an explicit query.

Exchange Server 2007 provides an updated and friendly set of "precanned" filter criteria that can be used to easily create DDGs. These precanned filters replace the older, overwhelming precanned filters available in Exchange Server 2003 with the most common precanned filters administrators use.

Additionally, if you need to use a filter outside of the scope of the available precanned filters, PowerShell OPATH filter syntax can be used to construct a custom filter query to meet the specific filter needs.

MailPublicFolder:

A MailPublicFolder is an AD object that is made available only after Exchange is installed. These objects only exist for the purpose of mail-enabling public folders, so they cannot exist as non-mail-enabled entities.

Recipient:

A Recipient is any of these previously discussed AD objects after it has been mail or mailbox enabled. All Mailboxes, MailUsers, MailContacts, DistributionGroups, DynamicDistributionGroups, and MailPublicFolders are Recipient objects. Recipient noun is typically used when your goal is to filter against the umbrella of all recipient types.

Exchange Server 2007 Recipient management verbs

Now that we've covered the basic recipient management nouns, let's move on to the verbs. We have a very specific pattern for the verbs that can be explained without even incorporating knowledge of the noun:

- New

- Enable

- Disable

- Remove

- Get

- Set

New:

New verb is used to indicate that you wish to create a new object in the AD and configure it as a recipient object. In order for the New verb to succeed, you must have the required AD rights to create the object (typically at least Account Operator for User, Group, Contact objects). Additionally, you must have rights to the "Exchange property set" attributes so that you can provision the Exchange properties on the AD object.

This verb is typically used in the case where "Split permissions" are not being used and one team owns the provisioning process for AD objects and Exchange recipients.

Since we only create new objects that are recipient objects, there is no concept of New-User, New-Group, or New-Contact. Similarly, we do not create New-MailPublicFolder directly (they must already exist and can only be "enabled"). However, there is New-Mailbox, New-MailContact, New-MailUser, New-DistributionGroup, and New-DynamicDistributionGroup.

Enable:

Enable verb is used to indicate that you wish to set Exchange properties on an existing object in the AD in order to provision it as a recipient object. In order for the Enable verb to succeed, you must have rights to the "Exchange property set" attributes so that you can provision the Exchange properties on the AD object. It is not generally necessary that you have "AD property set" rights from a group like Account Operators for this verb to succeed.

This verb is typically used in the case where "Split permissions" are in effect and AD objects are provisioned independently (and by a different team) than the Exchange provisioning.

There is no concept of Enable-DynamicDistributionGroup since these objects can only exist if they are already mail-enabled. However, there is Enable-Mailbox, Enable-MailContact, Enable-MailUser, Enable-DistributionGroup, and Enable-MailPublicFolder. Additionally, we add the concept of Enable-UMMailbox to configure UM-specific settings on an existing mailbox object.

It is a common use of the Get-* (User, Contact, Group) cmdlets to select some set of objects to be piped ("|") into the respective Enable verb.

Disable:

Disable verb is used to indicate that you wish to remove Exchange properties on an existing recipient object in the AD in order to discontinue its use as a recipient object. In order for the Disable verb to succeed, you must have rights to the "Exchange property set" attributes so that you can remove the Exchange properties from the AD object. It is not generally necessary that you have "AD property set" rights from a group like Account Operators for this verb to succeed.

This verb is typically used in the case where "Split permissions" are in effect and AD objects are provisioned independently (and by a different team) than the Exchange provisioning.

There is no concept of Disable-DynamicDistributionGroup since these objects can exist if they are mail-enabled. However, there is Disable-Mailbox, Disable-MailContact, Disable-MailUser, Disable-DistributionGroup, and Disable-MailPublicFolder. Additionally, we add the concept of Disable-UMMailbox to remove UM-specific settings from an existing mailbox object, leaving the rest of the mailbox settings intact.

It is a common use of the Get-User, Get-Contact, and Get-Group cmdlets to select some set of objects to be piped ("|") into the respective Enable verb.

Remove:

Remove verb is used to indicate that you wish to remove an existing recipient object from the AD. Note that this is a removal of the AD object, not just the Exchange properties. In order for the Remove verb to succeed, you must have the required AD rights to remove the AD object (typically at least Account Operator for User, Group, Contact objects).

This verb is typically used in the case where "Split permissions" are not being used and one team owns the provisioning process for AD objects and Exchange recipients.

Since we only remove AD objects that are recipient objects, there is no concept of Remove-User, Remove-Group, or Remove-Contact. Similarly, we do not Remove-MailPublicFolder directly (instead they must be mail "disabled"). However, there is Remove-Mailbox, Remove-MailContact, Remove-MailUser, Remove-DistributionGroup, and Remove-DynamicDistributionGroup.

Get:

Get verb is used to return some object or objects, including their property details. Couple of typical uses of the Get verb:

Inspect some specific property or properties on an object directly

Filter some set of objects down based on specific criteria and return only that filtered set of objects

Pipe some group of objects into a different cmdlet for some additional action

For Get verb to succeed you just need to have read access to the object or objects being read.

Get is a very powerful verb with many, many additional uses not described here. It is a standard verb for PowerShell and you'll find it used in this same capacity for much more than just recipient management.

Set:

Set verb is used to write a change to the property details of some object or objects. For Set verb to succeed you need to have write access to the object or objects being written. Note that in some cases this may require "Exchange Recipient Administrator" role delegation, and in other cases this may require AD permissions like "Account Operator". What rights are required will depend on which noun is being used and which properties are being "set".

Note that Set verb on some nouns has additional uses (for instance "mailbox type" conversion for Set-Mailbox). Also note that there is no concept of "Set" for Recipient noun, as this noun is used just as an means of conveniently aggregating the multiple recipient types together when filtering for output.

Miscellaneous

Note that not all verbs are available for all nouns (notice there is no "set-recipient" or "new-user", among others).

Additionally, note that there are a couple of oddball verbs that only apply to one noun or have special behavior with only one noun. The most obvious examples are:

Connect-Mailbox

Add-DistributionGroupMember

Remove-DistributionGroupMember

the storeMailbox purge behavior on "Remove-Mailbox"

- Evan Dodds

Comments (5)
  1. So there’s no way to manage NOT mail-enabled PFs using EMS?

  2. Evan Dodds says:

    Dmitry – you can definitely manage PFs that are not mail-enabled (and the non-mail properties of mail-enabled public folders), this is just not part of "recipient management" which is why I didn’t include it. The set of verbs is roughly the same, but the noun is "PublicFolder" rather than "MailPublicFolder".

  3. Nima says:

    Hi, what about parameters for these commandlets. Is there a place

    we can go to see what are valid values for each parameter?  We don’t

    seem to have them available in help.

    Thanks

    Nima

  4. evan says:

    Nima – you can always get the quick list of parameters for a cmdlet by doing:  Get-Command <the cmdlet> | fl

    For example: Get-Command New-Mailbox | fl

    That’ll show you the full set of parameters (and will show how they break out into multiple parameter sets for some cmdlets).

    A more verbose, but perhaps easier, way is to just do <the cmdlet> -? or do Help <the cmdlet>.

    Help New-Mailbox

    New-Mailbox -?

    Evan

  5. Anonymous says:

    I have previously listed the progress we’ve been making in posting ITPro focused Systems Management blog

Comments are closed.

Skip to main content