How to create user accounts and mailboxes with PowerShell

mailboxesThere are lots of tools available to the admin for creating new users in Active Directory, including Active Directory Users and Computers, the Active Directory Administrative Center, and the command line tools like dsadd and net user. When administering Exchange 2010, you will probably find yourself creating mailboxes using the GUI when you provision new user accounts, however, there are times where you need to create a mailbox outside of using ADUC. Whether there is a one off need, something happened during user creation that wasn’t quite right (like the user’s name was misspelled in AD,) you’re creating a resource or a shared mailbox, or you want to programmatically create user accounts and mailboxes with a script, the Exchange Management Shell (EMS,) or PowerShell to its friends, is a great way to go when you want to script this out.

The biggest benefit to using the Exchange Management Shell over dsadd is that you can specify the parameters needed for mailboxes, like SMTP addresses and mailbox databases. DSADD is still a very useful tool, but if you are looking for a one-stop shop command and you are using Exchange, the new-mailbox command will be your go-to guy.

The new-mailbox command

New-mailbox is an Exchange Management Shell cmdlet with more options than you can count. As with every other PowerShell cmdlet, you can get more information about it using the get-help cmdlet (aliased as man) or by checking out the online help on TechNet. This command, when entered without parameters, will walk you through creating an AD user with a mailbox, prompting you for the minimum required parameters.

While this might be enough to get you going, let’s look at some of the more useful options for this command. You can check out the full list by either checking out the TechNet site linked below, or by entering the man new-mailbox cmd.

-Name <String> This is, of course, the mailbox name.
-Password <SecureString> The user’s password, stored as a SecureString meaning we cannot display it again later.
-UserPrincipalName <String> The user’s UPN name in AD, in the format username@domain.
-Alias <String> An alias, which will simplify finding the user in the GAL.
-Database <DatabaseIdParameter> The database to store the user’s mailbox.
-DisplayName <String> The user’s display name in AD.
-FirstName <String> The user’s first name.
-LastName <String> The user’s surname.
-PrimarySmtpAddress <SmtpAddress> The primary SMTP address is their email address, in the form mailbox@fqdn.
-ResetPasswordOnNextLogon <$true | $false> Sets the flag controlling whether or not the user must change their password at next logon.
-SamAccountName <String> The user’s pre-Windows 2000 name, which is specified simply as a 15 character (or less) string.

Here are two examples of how to use this command.

Example one

This command creates an Active Directory user for John Smith in the CorpUsers OU, with a mailbox on the UserDatastore database, and an initial password that must be changed at next logon. It first prompts you for the password which it will store “-AsSecureString” meaning that it cannot be displayed again.

$password = Read-Host "Enter password" -AsSecureString
New-Mailbox -UserPrincipalName -Alias john
-Database "UserDatastore" -Name JohnSmith –OrganizationalUnit
CorpUsers -Password $password -FirstName John -LastName Smith
-DisplayName "John Smith" -ResetPasswordOnNextLogon $True

Example two

This command creates a resource mailbox for a conference room in the CorpResources OU, using the CorpResources database, and requiring the password to be set at next logon. This sets the alias as ChaConf1, and will prompt you for the password once you hit enter.

New-Mailbox -UserPrincipalName
-Alias ChaConf1 -Name CharlotteConferenceRoom1 -Database
"CorpResources" -OrganizationalUnit ConferenceRooms -Room
-ResetPasswordOnNextLogon $True

Example three

This command creates a mailbox for an existing user without a mailbox.

Enable-Mailbox -Identity:’ Smith'
-Alias:'JoeSmith' -Database: 'UserDatastore'

This is just a taste of what you can do with PowerShell and the new-mailbox command. There is even more information available about using the new-mailbox command using the online help in the shell, or on TechNet.

Written by Ed Fisher

An InfoTech professional, aficionado of capsaicin, and Coffea canephora (but not together,) I’ve been getting my geek on full-time since 1993, and have worked with information technology in some capacity since 1986. Stated simply, if you need to get information securely from a to b, I’m your guy. I’m like "The Transporter," but for data, and without the car. And with a little more hair.


  1. Barry · July 27, 2012

    Hey Ed, I’m a little disappointed with your article. Does the tech industry really think we create our users one at a time so typing our John Smith with all the necessary switches resolves and Admin’s account creation nightmare? What if I want to create 500 users, do your examples above provide that kind of help?

    What if I have another system where users accounts are creating as a source, and it SSH’s into my AD account and I want it to pass along the user information for AD user creation?

    Anyone that can type Get-Help can use off the shelf PS scripts. How to integrate them with other processes is the trick.

Leave A Reply