In this article by Jonas Andersson and Mike Pfeiffer, authors of the book Microsoft Exchange Server PowerShell Cookbook – Third Edition, we will see how the mailboxes are managed in the Exchange Management Shell.
(For more resources related to this topic, see here.)
Adding, modifying, and removing mailboxes
One of the most common tasks performed within the Exchange Management Shell is mailbox management. In this recipe, we’ll take a look at the command syntax required to create, update, and remove mailboxes from your Exchange organization. The concepts outlined in this recipe can be used to perform basic day-to-day tasks and will be useful for more advanced scenarios, such as creating mailboxes in bulk.
How to do it…
Let’s see how to add, modify, and delete mailboxes using the following steps:
- Let’s start off by creating a mailbox-enabled Active Directory user account. To do this, we can use the New-Mailbox cmdlet, as shown in the following example:
$password = ConvertTo-SecureString -AsPlainText P@ssw0rd `
-Force
New-Mailbox -UserPrincipalName [email protected] `
-Alias dave `
-Database DAGDB1 `
-Name 'Dave Jones' `
-OrganizationalUnit Sales `
-Password $password `
-FirstName Dave `
-LastName Jones `
-DisplayName 'Dave Jones' - Once the mailbox has been created, we can modify it using the Set-Mailbox cmdlet:
Set-Mailbox -Identity dave `
-UseDatabaseQuotaDefaults $false `
-ProhibitSendReceiveQuota 5GB `
-IssueWarningQuota 4GB - To remove the Exchange attributes from the Active Directory user account and mark the mailbox in the database for removal, use the Disable-Mailbox cmdlet:
Disable-Mailbox -Identity dave -Confirm:$false
How it works…
When running the New-Mailbox cmdlet, the -Password parameter is required, and you need to provide a value for it, using a secure string object. As you can see from the code, we used the ConvertTo-SecureString cmdlet to create a $password variable that stores a specified value as an encrypted string. This $password variable is then assigned to the -Password parameter when running the cmdlet. It’s not required to first store this object in a variable; we could have done it inline, as shown next:
New-Mailbox -UserPrincipalName [email protected] `
-Alias dave `
-Database DAGDB1 `
-Name 'Dave Jones' `
-OrganizationalUnit Sales `
-Password (ConvertTo-SecureString -AsPlainText P@ssw0rd -Force) `
-FirstName Dave `
-LastName Jones `
-DisplayName 'Dave Jones'
Keep in mind that the password used here needs to comply with your Active Directory password policies, which may enforce a minimum password length and have requirements for complexity.
Only a few parameters are actually required when running New-Mailbox, but the cmdlet itself supports several useful parameters that can be used to set certain properties when creating the mailbox. You can run Get-Help New-Mailbox -Detailed to determine which additional parameters are supported.
The New-Mailbox cmdlet creates a new Active Directory user and then mailbox-enables that account. We can also create mailboxes for existing users with the Enable-Mailbox cmdlet, using a syntax similar to the following:
Enable-Mailbox steve -Database DAGDB1
The only requirement when running the Enable-Mailbox cmdlet is that you need to provide the identity of the Active Directory user that should be mailbox-enabled. In the previous example, we specified the database in which the mailbox should be created, but this is optional. The Enable-Mailbox cmdlet supports a number of other parameters that you can use to control the initial settings for the mailbox.
You can use a simple one-liner to create mailboxes in bulk for existing Active Directory users:
Get-User -RecipientTypeDetails User | Enable-Mailbox -Database DAGDB1
Notice that we run the Get-User cmdlet, specifying User as the value for the -RecipientTypeDetails parameter. This will retrieve only the accounts in Active Directory that have not been mailbox-enabled. We then pipe those objects down to the Enable-Mailbox cmdlet and mailboxes will be created for each of those users in one simple operation.
Once the mailboxes have been created, they can be modified with the Set-Mailbox cmdlet. As you may recall from our original example, we used the Set-Mailbox cmdlet to configure the custom storage quota settings after creating a mailbox for Dave Jones. Keep in mind that the Set-Mailbox cmdlet supports over 100 parameters, so anything that can be done to modify a mailbox can be scripted.
Bulk modifications to mailboxes can be done easily by taking advantage of the pipeline and the Set-Mailbox cmdlet. Instead of configuring storage quotas on a single mailbox, we can do it for multiple users at once:
Get-Mailbox -OrganizationalUnit contoso.com/sales |
Set-Mailbox -UseDatabaseQuotaDefaults $false `
-ProhibitSendReceiveQuota 5GB `
-IssueWarningQuota 4GB
Here, we are simply retrieving every mailbox in the sales OU using the Get-Mailbox cmdlet. The objects returned from this command are piped down to Set-Mailbox, which then modifies the quota settings for each mailbox in one shot.
The Disable-Mailbox cmdlet will strip the Exchange attributes from an Active Directory user and will disconnect the associated mailbox. By default, disconnected mailboxes are retained for 30 days. You can modify this setting on the database that holds the mailbox. In addition to this, you can also use the Remove-Mailbox cmdlet to delete both the Active Directory account and the mailbox at once:
Remove-Mailbox -Identity dave -Confirm:$false
After running this command, the mailbox will be purged once it exceeds the deleted mailbox retention setting on the database. One common mistake is when administrators use the Remove-Mailbox cmdlet when the Disable-Mailbox cmdlet should have been used. It’s important to remember that the Remove-Mailbox cmdlet will delete the Active Directory user account and mailbox, while the Disable-Mailbox cmdlet only removes the mailbox, but the Active Directory user account still remains.
There’s more…
When we ran the New-Mailbox cmdlet in the previous examples, we assigned a secure string object to the –Password parameter using the ConvertTo-SecureString cmdlet. This is a great technique to use when your scripts need complete automation, but you can also allow an operator to enter this information interactively. For example, you might build a script that prompts an operator for a password when creating one or more mailboxes. There are a couple of ways you can do this. First, you can use the Read-Host cmdlet to prompt the user running the script to enter a password:
$pass = Read-Host "Enter Password" -AsSecureString
Once a value has been entered in the shell, your script can assign the $pass variable to the -Password parameter of the New-Mailbox cmdlet.
Alternatively, you can supply a value for the -Password parameter using the Get-Credential cmdlet:
New-Mailbox -Name Dave -UserPrincipalName [email protected] `
-Password (Get-Credential).password
You can see that the value we are assigning to the -Password parameter in this example is actually the password property of the object returned by the Get-Credential cmdlet. Executing this command will first launch a Windows authentication dialog box, where the caller can enter a username and password. Once the credential object has been created, the New-Mailbox cmdlet will run. Even though a username and password must be entered in the authentication dialog box, only the password value will be used when the command executes.
Setting the Active Directory attributes
Some of the Active Directory attributes that you may want to set when creating a mailbox might not be available when using the New-Mailbox cmdlet. Good examples of this are a user’s city, state, company, and department attributes. In order to set these attributes, you’ll need to call the Set-User cmdlet after the mailbox has been created:
Set-User –Identity dave –Office IT –City Seattle –State Washington
You can run Get-Help Set-User -Detailed to view all of the available parameters supported by this cmdlet.
Notice that the Set-User cmdlet is an Active Directory cmdlet and not an Exchange cmdlet.
In the examples using the New-Mailbox cmdlet to create new mailboxes, it is not required to use all these parameters from the example. The only required parameters are UserPrincipalName, Name, and Password.
Working with contacts
Once you’ve started managing mailboxes using the Exchange Management Shell, you’ll probably notice that the concepts and command syntax used to manage contacts are very similar. The difference, of course, is that we need to use a different set of cmdlets. In addition, we also have two types of contacts to deal with in Exchange. We’ll take a look at how you can manage both of them in this recipe.
How to do it…
Let’s see how to work with contacts using the following steps:
- To create a mail-enabled contact, use the New-MailContact cmdlet:
New-MailContact -Alias rjones `
-Name "Rob Jones" `
-ExternalEmailAddress [email protected] `
-OrganizationalUnit sales - Mail-enabled users can be created with the New-MailUser cmdlet:
New-MailUser -Name 'John Davis' `
-Alias jdavis `
-UserPrincipalName [email protected] `
-FirstName John `
-LastName Davis `
-Password (ConvertTo-SecureString -AsPlainText P@ssw0rd `
-Force) `
-ResetPasswordOnNextLogon $false `
-ExternalEmailAddress [email protected]
How it works…
Mail contacts are useful when you have external e-mail recipients that need to show up in your global address list. When you use the New-MailContact cmdlet, an Active Directory contact object is created and mail-enabled with the external e-mail address assigned. You can mail-enable an existing Active Directory contact using the Enable-MailContact cmdlet.
Mail users are similar to mail contacts in the way that they have an associated external e-mail address. The difference is that these objects are mail-enabled Active Directory users and this explains why we need to assign a password when creating the object. You might use a mail user for a contractor who works onsite in your organization and needs to be able to log on to your domain. When users in your organization need to e-mail this person, they can select them from the global address list and messages sent to these recipients will be delivered to the external address configured for the account.
When dealing with mailboxes, there are a couple of things that should be taken into consideration when it comes to removing contacts and mail users. You can remove the Exchange attributes from a contact using the Disable-MailContact cmdlet. The Remove-MailContact cmdlet will remove the contact object from the Active Directory and Exchange. Similarly, the Disable-MailUser and Remove-MailUser cmdlets work in the same fashion.
There’s more…
Like mailboxes, mail contacts and mail-enabled user accounts have several Active Directory attributes that can be set, such as the job title, company, department, and so on. To update these attributes, you can use the Set-* cmdlets that are available for each respective type. For example, to update our mail contact, we can use the Set-Contact cmdlet with the following syntax:
Set-Contact -Identity rjones `
-Title 'Sales Contractor' `
-Company Fabrikam `
-Department Sales
To modify the same settings for a mail-enabled user, use the Set-User cmdlet:
Set-User -Identity jdavis `
-Title 'Sales Contractor' `
-Company Fabrikam `
-Department Sales
Both cmdlets can be used to modify a number of different settings. Use the help system to view all of the available parameters.
Managing distribution groups
In many Exchange environments, distribution groups are heavily relied upon and require frequent changes. This recipe will cover the creation of distribution groups and how to add members to groups, which might be useful when performing these tasks interactively in the shell or through automated scripts.
How to do it…
Let’s see how to create distribution groups using the following steps:
- To create a distribution group, use the New-DistributionGroup cmdlet:
New-DistributionGroup -Name Sales
- Once the group has been created, adding multiple members can be done easily using a one-liner, as follows:
Get-Mailbox -OrganizationalUnit Sales |
Add-DistributionGroupMember -Identity Sales - We can also create distribution groups whose memberships are set dynamically:
New-DynamicDistributionGroup -Name Accounting `
-Alias Accounting `
-IncludedRecipients MailboxUsers,MailContacts `
-OrganizationalUnit Accounting `
-ConditionalDepartment accounting,finance `
-RecipientContainer contoso.com
How it works…
There are two types of distribution groups that can be created with Exchange. Firstly, there are regular distribution groups, which contain a distinct list of users. Secondly, there are dynamic distribution groups, whose members are determined at the time a message is sent based on a number of conditions or filters that have been defined. Both types have a set of cmdlets that can be used to add, remove, update, enable, or disable these groups.
By default, when creating a standard distribution group, the group scope will be set to Universal. You can create a mail-enabled security group using the New-DistributionGroup cmdlet by setting the -Type parameter to Security. If you do not provide a value for the -Type parameter, the group will be created using the Distribution group type.
You can mail-enable an existing Active Directory universal distribution group using the Enable-DistributionGroup cmdlet.
After creating the Sales distribution group in our previous example, we added all of the mailboxes in the Sales OU to the group using the Add-DistributionGroupMember cmdlet. You can do this in bulk, or for one user at a time, using the –Member parameter:
Add-DistributionGroupMember -Identity Sales -Member administrator
Dynamic distribution groups determine their membership based on a defined set of filters and conditions. When we created the Accounting distribution group, we used the -IncludedRecipients parameter to specify that only the MailboxUsers and MailContacts object types would be included in the group. This eliminates resource mailboxes, groups, or mail users from being included as members. The group will be created in the Accounting OU based on the value used with the -OrganizationalUnit parameter. Using the –ConditionalDepartment parameter, the group will only include users that have a department setting of either Accounting or Finance. Finally, since the -RecipientContainer parameter is set to the FQDN of the domain, any user located in the Active Directory can potentially be included in the group. You can create more complex filters for dynamic distribution groups using a recipient filter.
You can modify both group types using the Set-DistributionGroup and Set-DynamicDistributionGroup cmdlets.
There’s more…
When dealing with other recipient types, there are a couple of things that should be taken into consideration when it comes to removing distribution groups. You can remove the Exchange attributes from a group using the Disable-DistributionGroup cmdlet. The Remove-DistributionGroup cmdlet will remove the group object from the Active Directory and Exchange.
Managing resource mailboxes
In addition to mailboxes, groups, and external contacts, recipients can also include specific rooms or pieces of equipment. Locations such as a conference room or a classroom can be given a mailbox so that they can be reserved for meetings. Equipment mailboxes can be assigned to physical, non-location specific resources, such as laptops or projectors, and can then be checked out to individual users or groups by booking a time with the mailbox. In this recipe, we’ll take a look at how you can manage resource mailboxes using the Exchange Management Shell.
How to do it…
When creating a resource mailbox from within the shell, the syntax is similar to creating a mailbox for a regular user. For example, you still use the New-Mailbox cmdlet when creating a resource mailbox:
New-Mailbox -Name "CR23" -DisplayName "Conference Room 23" `
-UserPrincipalName [email protected] -Room
How it works…
There are two main differences when it comes to creating a resource mailbox, as opposed to a standard user mailbox. First, you need to use either the -Room switch parameter or the -Equipment switch parameter to define the type of resource mailbox that will be created. Second, you do not need to provide a password value for the user account. When using either of these resource mailbox switch parameters to create a mailbox, the New-Mailbox cmdlet will create a disabled Active Directory user account that will be associated with the mailbox.
The entire concept of room and equipment mailboxes revolves around the calendars used by these resources. If you want to reserve a room or a piece of equipment, you book a time through Outlook or OWA with these resources for the duration that you’ll need them. The requests sent to these resources need to be accepted, either by a delegate or automatically using the Resource Booking Attendant.
To configure the room mailbox created in the previous example, to automatically accept new meeting requests, we can use the Set-CalendarProcessing cmdlet to set the Resource Booking Attendant for that mailbox to AutoAccept:
Set-CalendarProcessing CR23 -AutomateProcessing AutoAccept
When the Resource Booking Attendant is set to AutoAccept, the request will be immediately accepted as long as there is no conflict with another meeting. If there is a conflict, an e-mail message will be returned to the requestor, which explains that the request was declined due to scheduling conflicts. You can allow conflicts by adding the –AllowConflicts switch parameter to the previous command.
When working with resource mailboxes with AutomateProcessing set to AutoAccept, you’ll get an automated e-mail response from the resource after booking a time. This e-mail message will explain whether the request was accepted or declined, depending on your settings. You can add an additional text to the response message that the meeting organizer will receive using the following syntax:
Set-CalendarProcessing -Identity CR23 `
-AddAdditionalResponse $true `
-AdditionalResponse 'For Assistance Contact Support at Ext. #3376'
This example uses the Set-CalendarProcessing cmdlet to customize the response messages sent from the CR23 room mailbox. You can see here that we added a message that tells the user the help desk number to call if assistance is required. Keep in mind that you can only add an additional response text, when the AutomateProcessing property is set to AutoAccept.
If you do not want to automate the calendar processing for a resource mailbox, then you’ll need to add delegates that can accept or deny meetings for that resource. Again, we can turn to the Set-CalendarProcessing cmdlet to accomplish this:
Set-CalendarProcessing -Identity CR23 `
-ResourceDelegates "[email protected]","[email protected]" `
-AutomateProcessing None
In this example, we added two delegates to the resource mailbox and have turned off automated processing. When a request comes into the CR23 mailbox, both Steve and Joe will be notified and can accept or deny the request on behalf of the resource mailbox.
There’s more…
When it comes to working with resource mailboxes, another useful feature is the ability to assign custom resource properties to rooms and equipment resources. For example, you may have a total of 5, 10, or 15 conference rooms, but maybe only four of these have whiteboards. It might be useful for your users to know this information when booking a resource for a meeting, where they will be conducting a training session.
Using the shell, we can add custom resource properties to the Exchange organization by modifying the resource schema. Once these custom resource properties have been added, they can then be assigned to specific resource mailboxes.
You can use the following code to add a whiteboard resource property to the Exchange organization’s resource schema:
Set-ResourceConfig -ResourcePropertySchema 'Room/Whiteboard'
Now that the whiteboard resource property is available within the Exchange organization, we can add this to our Conference Room 23 mailbox using the following command:
Set-Mailbox -Identity CR23 -ResourceCustom Whiteboard
When users access the Select Rooms or Add Rooms dialog box in Outlook 2007, 2010, or 2013, they will see that Conference Room 23 has a whiteboard available.
Converting mailboxes
If you’ve moved from an old version, you may have a number of mailboxes that were used as resource mailboxes. Once these mailboxes have been moved they will be identified as Shared mailboxes. You can convert them to different types using the Set-Mailbox cmdlet so that they’ll have all of the properties of a resource mailbox:
Get-Mailbox conf* | Set-Mailbox -Type Room
You can run the Set-Mailbox cmdlet against each mailbox one at a time and convert them to Room mailboxes, using the -Type parameter. Or, if you use a common naming convention, you may be able to do them in bulk by retrieving a list of mailboxes using a wildcard and piping them to Set-Mailbox, as shown previously.
Summary
In this article we have discussed how the various types of mailboxes are managed, how to set up the Active Directory attributes, how to work with contacts and distribution groups.
Resources for Article:
Further resources on this subject:
- Unleashing Your Development Skills with PowerShell [Article]
- Inventorying Servers with PowerShell [Article]
- Exchange Server 2010 Windows PowerShell: Working with Address Lists [Article]
