How to do it...

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've 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. There's no requirement to first store this object in a variable; we could have done it inline, as shown next:

New-Mailbox -UserPrincipalName dave@contoso.com `
-Alias dave `
-Database DAGDB1 `
-Name DaveJones `
-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 syntax similar to the following:

Enable-Mailbox steve -Database DAGDB1

The only requirement when running the Enable-Mailbox cmdlet is that you provide the identity of the Active Directory user that should be mailbox-enabled. In the previous example, we've 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've 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 tothe Enable-Mailbox cmdlet and mailboxes are created for each of those users in one simple operation.

Once 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 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 that command are piped down to Set-Mailbox which 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.

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 into 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 dave@contoso.com `
-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 into the authentication dialog box, only the password value will be used when the command executes.

Set-User –Identity dave –Office IT –City Seattle –State Washington

See also