Applies to: Exchange Server 2007
Topic Last Modified: 2008-03-13

Use the New-Mailbox cmdlet to create a new user in the Active Directory directory service and mailbox-enable this new user.

Syntax

New-Mailbox -Name <String> -Database <DatabaseIdParameter> -OrganizationalUnit <OrganizationalUnitIdParameter> -Password <SecureString> -UserPrincipalName <String> [-ActiveSyncMailboxPolicy <MailboxPolicyIdParameter>] [-Alias <String>] [-DisplayName <String>] [-DomainController <Fqdn>] [-FirstName <String>] [-Initials <String>] [-LastName <String>] [-ManagedFolderMailboxPolicy <MailboxPolicyIdParameter>] [-ManagedFolderMailboxPolicyAllowed <SwitchParameter>] [-ResetPasswordOnNextLogon <$true | $false>] [-SamAccountName <String>] [-TemplateInstance <PSObject>]
New-Mailbox -Name <String> -Database <DatabaseIdParameter> -LinkedDomainController <String> -LinkedMasterAccount <UserIdParameter> -OrganizationalUnit <OrganizationalUnitIdParameter> -UserPrincipalName <String> [-ActiveSyncMailboxPolicy <MailboxPolicyIdParameter>] [-Alias <String>] [-DisplayName <String>] [-DomainController <Fqdn>] [-FirstName <String>] [-Initials <String>] [-LastName <String>] [-LinkedCredential <PSCredential>] [-ManagedFolderMailboxPolicy <MailboxPolicyIdParameter>] [-ManagedFolderMailboxPolicyAllowed <SwitchParameter>] [-Password <SecureString>] [-ResetPasswordOnNextLogon <$true | $false>] [-SamAccountName <String>] [-TemplateInstance <PSObject>]
New-Mailbox -Name <String> -Database <DatabaseIdParameter> -OrganizationalUnit <OrganizationalUnitIdParameter> -Room <SwitchParameter> -UserPrincipalName <String> [-ActiveSyncMailboxPolicy <MailboxPolicyIdParameter>] [-Alias <String>] [-DisplayName <String>] [-DomainController <Fqdn>] [-FirstName <String>] [-Initials <String>] [-LastName <String>] [-ManagedFolderMailboxPolicy <MailboxPolicyIdParameter>] [-ManagedFolderMailboxPolicyAllowed <SwitchParameter>] [-Password <SecureString>] [-ResetPasswordOnNextLogon <$true | $false>] [-SamAccountName <String>] [-TemplateInstance <PSObject>]
New-Mailbox -Name <String> -Database <DatabaseIdParameter> -Equipment <SwitchParameter> -OrganizationalUnit <OrganizationalUnitIdParameter> -UserPrincipalName <String> [-ActiveSyncMailboxPolicy <MailboxPolicyIdParameter>] [-Alias <String>] [-DisplayName <String>] [-DomainController <Fqdn>] [-FirstName <String>] [-Initials <String>] [-LastName <String>] [-ManagedFolderMailboxPolicy <MailboxPolicyIdParameter>] [-ManagedFolderMailboxPolicyAllowed <SwitchParameter>] [-Password <SecureString>] [-ResetPasswordOnNextLogon <$true | $false>] [-SamAccountName <String>] [-TemplateInstance <PSObject>]
New-Mailbox -Name <String> -Database <DatabaseIdParameter> -OrganizationalUnit <OrganizationalUnitIdParameter> -Shared <SwitchParameter> -UserPrincipalName <String> [-ActiveSyncMailboxPolicy <MailboxPolicyIdParameter>] [-Alias <String>] [-DisplayName <String>] [-DomainController <Fqdn>] [-FirstName <String>] [-Initials <String>] [-LastName <String>] [-ManagedFolderMailboxPolicy <MailboxPolicyIdParameter>] [-ManagedFolderMailboxPolicyAllowed <SwitchParameter>] [-Password <SecureString>] [-ResetPasswordOnNextLogon <$true | $false>] [-SamAccountName <String>] [-TemplateInstance <PSObject>]

Parameters

Parameter Required Type Description

Database

Required

Microsoft.Exchange.Configuration.Tasks.DatabaseIdParameter

The Database parameter specifies which Exchange database will contain the new user's mailbox. You can use the following values:

  • GUID of the database

  • Database name

  • Server name\database name

  • Server name\storage group\database name

Equipment

Required

System.Management.Automation.SwitchParameter

The Equipment parameter specifies that the type of resource is equipment, if this mailbox is a resource mailbox. This parameter is required only if you are creating a resource mailbox.

LinkedDomainController

Required

System.String

The LinkedDomainController parameter specifies the domain controller in the forest where the user account resides. The domain controller in this forest is used to get security information for the account specified by the LinkedMasterAccount parameter. This parameter is required only if you are creating a linked mailbox.

LinkedMasterAccount

Required

Microsoft.Exchange.Configuration.Tasks.UserIdParameter

The LinkedMasterAccount parameter specifies the master account in the forest where the user account resides. The master account is the account to link the mailbox to. The master account will grant access to the mailbox. This parameter is required only if you are creating a linked mailbox. You can use one of the following values:

  • GUID

  • Distinguished name (DN)

  • Domain\Account

  • User principal name (UPN)

  • LegacyExchangeDN

  • SmtpAddress

  • Alias

Name

Required

System.String

The Name parameter specifies the user's name. This is the name that appears in Active Directory Users and Computers. This is also the user name that appears in Recipient Properties on the User Information tab.

OrganizationalUnit

Required

Microsoft.Exchange.Configuration.Tasks.OrganizationalUnitIdParameter

The OrganizationalUnit parameter specifies the container where the user will be created.

Password

Required

System.Security.SecureString

The Password parameter specifies the initial password for the newly created user. This parameter is not required if you are creating a linked mailbox, resource mailbox, or shared mailbox, because the user account for these types of mailboxes will be disabled.

Room

Required

System.Management.Automation.SwitchParameter

The Room parameter specifies that the type of resource is a room, if this mailbox is a resource mailbox. This parameter is required only if you are creating a resource mailbox.

Shared

Required

System.Management.Automation.SwitchParameter

The Shared parameter specifies that you are creating a shared mailbox. A shared mailbox is a mailbox to which multiple users can log on. This mailbox is not associated with any of the users that can log on. It is associated with a disabled user account.

This parameter is required only if you are creating a shared mailbox.

UserPrincipalName

Required

System.String

The UserPrincipalName parameter specifies the user principal name (UPN) for this mailbox. This is the logon name for the user. The UPN consists of a user name and a suffix. Typically, the suffix is the domain name where the user account resides.

ActiveSyncMailboxPolicy

Optional

Microsoft.Exchange.Configuration.Tasks.MailboxPolicyIdParameter

The ActiveSyncMailboxPolicy parameter specifies the mailbox policy to enable for the mailbox that you create. If you do not specify this parameter, the default mailbox policy is used.

Alias

Optional

System.String

The Alias parameter specifies the e-mail alias of the user that you are creating.

The alias can be a combination of characters separated by a period with no intervening spaces. Do not use special characters in the alias.

DisplayName

Optional

System.String

The DisplayName parameter specifies the display name for the new user created with this mailbox. The DisplayName is the name that appears in the Exchange Management Console under Recipient Configuration. The DisplayName also appears in Active Directory Users and Computers on the user Properties General Tab.

DomainController

Optional

Microsoft.Exchange.Data.Fqdn

The DomainController parameter specifies the domain controller to use to write this configuration change to Active Directory. Use the fully qualified domain name (FQDN) of the domain controller that you want to use.

FirstName

Optional

System.String

The FirstName parameter specifies the first name of the user that you create.

Initials

Optional

System.String

The Initials parameter specifies the initials of the user that you create.

LastName

Optional

System.String

The LastName parameter specifies the last name of the user that you create.

LinkedCredential

Optional

System.Management.Automation.PSCredential

The LinkedCredential parameter specifies credentials to use to access the domain controller specified by the LinkedDomainController parameter. This parameter is optional, even if you are enabling a linked mailbox.

ManagedFolderMailboxPolicy

Optional

Microsoft.Exchange.Configuration.Tasks.MailboxPolicyIdParameter

The ManagedFolderMailboxPolicy parameter specifies the managed folder mailbox policy to enable for the mailbox that you create.

ManagedFolderMailboxPolicyAllowed

Optional

System.Management.Automation.SwitchParameter

The ManagedFolderMailboxPolicyAllowed parameter bypasses the warning that messaging records management features are not supported for e-mail clients using versions of Microsoft Outlook earlier than Outlook 2007. When a managed folder mailbox policy is assigned to a mailbox using the ManagedFolderMailboxPolicy parameter, the warning appears by default unless ManagedFolderMailboxPolicyAllowed is used.

Note:
Outlook 2003 Service Pack 3 clients are supported but are provided limited functionality for messaging records management.

ResetPasswordOnNextLogon

Optional

System.Boolean

If set to $true, the ResetPasswordOnNextLogon parameter specifies that the password in the Password parameter must be reset the next time the user logs on.

SamAccountName

Optional

System.String

The SamAccountName parameter specifies the logon name used to support clients and servers running older versions of the operating system, such as Microsoft Windows NT 4.0, Windows 95, Windows 98, and LAN Manager. This attribute must be less than 20 characters to support older clients.

If you do not specify this parameter, Active Directory will create a SAMAccountName automatically, based on the user principal name.

TemplateInstance

Optional

System.Management.Automation.PSObject

When an existing object is supplied to the TemplateInstance parameter, the command will use that object's configuration to create an exact duplicate of the object on a local or target server.

Detailed Description

To run the New-Mailbox cmdlet, the account you use must be delegated the following:

  • Exchange Recipient Administrator role

  • Account Operator role for the applicable Active Directory containers

For more information about permissions, delegating roles, and the rights that are required to administer Microsoft Exchange Server 2007, see Permission Considerations.

Input Types

Return Types

Errors

Error Description

 

Exceptions

Exceptions Description

 

Example

The first example shows how to create a user Chris Ashton in Active Directory and create a mailbox for the user. The mailbox is located on Storage Group 1, in Mailbox Database 1. The password must be reset at the next logon. To set the initial value of the password, this example creates a variable, $password, prompts you to enter a password, and assigns that password to the variable as a SecureString object.

The second example shows how to create a user in Active Directory and a resource mailbox for a conference room. The resource mailbox is located on Storage Group 1, in Mailbox Database 1. The password must be reset at the next logon. The Exchange Management Shell will prompt for the value of the initial password, because it is not specified.

Copy Code
$password = Read-Host "Enter password" -AsSecureString
New-mailbox -UserPrincipalName chris@contoso.com -alias chris -database "Storage Group 1\Mailbox Database 1" -Name ChrisAshton -OrganizationalUnit Users -password $password -FirstName Chris -LastName Ashton -DisplayName "Chris Ashton" -ResetPasswordOnNextLogon $true

New-Mailbox -UserPrincipalName confmbx@contoso.com -alias confmbx -name ConfRoomMailbox -database "Storage Group 1\Mailbox Database 1" -OrganizationalUnit Users -Room -ResetPasswordOnNextLogon $true