Applies to: Exchange Server 2007 SP3, Exchange Server 2007 SP2, Exchange Server 2007 SP1
Topic Last Modified: 2009-05-12

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> -Password <SecureString> -UserPrincipalName <String> [-ActiveSyncMailboxPolicy <MailboxPolicyIdParameter>] [-Alias <String>] [-Confirm [<SwitchParameter>]] [-DisplayName <String>] [-DomainController <Fqdn>] [-FirstName <String>] [-Initials <String>] [-LastName <String>] [-ManagedFolderMailboxPolicy <MailboxPolicyIdParameter>] [-ManagedFolderMailboxPolicyAllowed <SwitchParameter>] [-OrganizationalUnit <OrganizationalUnitIdParameter>] [-ResetPasswordOnNextLogon <$true \| $false>] [-SamAccountName <String>] [-TemplateInstance <PSObject>] [-UseRusServer <String>] [-WhatIf [<SwitchParameter>]]

New-Mailbox -Name <String> -Database
<DatabaseIdParameter> -Password <SecureString>
-UserPrincipalName <String> [-ActiveSyncMailboxPolicy
<MailboxPolicyIdParameter>] [-Alias <String>] [-Confirm
[<SwitchParameter>]] [-DisplayName <String>]
[-DomainController <Fqdn>] [-FirstName <String>]
[-Initials <String>] [-LastName <String>]
[-ManagedFolderMailboxPolicy <MailboxPolicyIdParameter>]
[-ManagedFolderMailboxPolicyAllowed <SwitchParameter>]
[-OrganizationalUnit <OrganizationalUnitIdParameter>]
[-ResetPasswordOnNextLogon <$true | $false>] [-SamAccountName
<String>] [-TemplateInstance <PSObject>] [-UseRusServer
<String>] [-WhatIf [<SwitchParameter>]]


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

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


New-Mailbox -Name <String> -Database <DatabaseIdParameter> -Equipment <SwitchParameter> -UserPrincipalName <String> [-ActiveSyncMailboxPolicy <MailboxPolicyIdParameter>] [-Alias <String>] [-Confirm [<SwitchParameter>]] [-DisplayName <String>] [-DomainController <Fqdn>] [-FirstName <String>] [-Initials <String>] [-LastName <String>] [-ManagedFolderMailboxPolicy <MailboxPolicyIdParameter>] [-ManagedFolderMailboxPolicyAllowed <SwitchParameter>] [-OrganizationalUnit <OrganizationalUnitIdParameter>] [-Password <SecureString>] [-ResetPasswordOnNextLogon <$true \| $false>] [-SamAccountName <String>] [-TemplateInstance <PSObject>] [-UseRusServer <String>] [-WhatIf [<SwitchParameter>]]

New-Mailbox -Name <String> -Database
<DatabaseIdParameter> -Equipment <SwitchParameter>
-UserPrincipalName <String> [-ActiveSyncMailboxPolicy
<MailboxPolicyIdParameter>] [-Alias <String>] [-Confirm
[<SwitchParameter>]] [-DisplayName <String>]
[-DomainController <Fqdn>] [-FirstName <String>]
[-Initials <String>] [-LastName <String>]
[-ManagedFolderMailboxPolicy <MailboxPolicyIdParameter>]
[-ManagedFolderMailboxPolicyAllowed <SwitchParameter>]
[-OrganizationalUnit <OrganizationalUnitIdParameter>]
[-Password <SecureString>] [-ResetPasswordOnNextLogon
<$true | $false>] [-SamAccountName <String>]
[-TemplateInstance <PSObject>] [-UseRusServer <String>]
[-WhatIf [<SwitchParameter>]]


New-Mailbox -Name <String> -Database <DatabaseIdParameter> -Shared <SwitchParameter> -UserPrincipalName <String> [-ActiveSyncMailboxPolicy <MailboxPolicyIdParameter>] [-Alias <String>] [-Confirm [<SwitchParameter>]] [-DisplayName <String>] [-DomainController <Fqdn>] [-FirstName <String>] [-Initials <String>] [-LastName <String>] [-ManagedFolderMailboxPolicy <MailboxPolicyIdParameter>] [-ManagedFolderMailboxPolicyAllowed <SwitchParameter>] [-OrganizationalUnit <OrganizationalUnitIdParameter>] [-Password <SecureString>] [-ResetPasswordOnNextLogon <$true \| $false>] [-SamAccountName <String>] [-TemplateInstance <PSObject>] [-UseRusServer <String>] [-WhatIf [<SwitchParameter>]]

New-Mailbox -Name <String> -Database
<DatabaseIdParameter> -Shared <SwitchParameter>
-UserPrincipalName <String> [-ActiveSyncMailboxPolicy
<MailboxPolicyIdParameter>] [-Alias <String>] [-Confirm
[<SwitchParameter>]] [-DisplayName <String>]
[-DomainController <Fqdn>] [-FirstName <String>]
[-Initials <String>] [-LastName <String>]
[-ManagedFolderMailboxPolicy <MailboxPolicyIdParameter>]
[-ManagedFolderMailboxPolicyAllowed <SwitchParameter>]
[-OrganizationalUnit <OrganizationalUnitIdParameter>]
[-Password <SecureString>] [-ResetPasswordOnNextLogon
<$true | $false>] [-SamAccountName <String>]
[-TemplateInstance <PSObject>] [-UseRusServer <String>]
[-WhatIf [<SwitchParameter>]]


New-Mailbox -Name <String> -Database <DatabaseIdParameter> -Room <SwitchParameter> -UserPrincipalName <String> [-ActiveSyncMailboxPolicy <MailboxPolicyIdParameter>] [-Alias <String>] [-Confirm [<SwitchParameter>]] [-DisplayName <String>] [-DomainController <Fqdn>] [-FirstName <String>] [-Initials <String>] [-LastName <String>] [-ManagedFolderMailboxPolicy <MailboxPolicyIdParameter>] [-ManagedFolderMailboxPolicyAllowed <SwitchParameter>] [-OrganizationalUnit <OrganizationalUnitIdParameter>] [-Password <SecureString>] [-ResetPasswordOnNextLogon <$true \| $false>] [-SamAccountName <String>] [-TemplateInstance <PSObject>] [-UseRusServer <String>] [-WhatIf [<SwitchParameter>]]

New-Mailbox -Name <String> -Database
<DatabaseIdParameter> -Room <SwitchParameter>
-UserPrincipalName <String> [-ActiveSyncMailboxPolicy
<MailboxPolicyIdParameter>] [-Alias <String>] [-Confirm
[<SwitchParameter>]] [-DisplayName <String>]
[-DomainController <Fqdn>] [-FirstName <String>]
[-Initials <String>] [-LastName <String>]
[-ManagedFolderMailboxPolicy <MailboxPolicyIdParameter>]
[-ManagedFolderMailboxPolicyAllowed <SwitchParameter>]
[-OrganizationalUnit <OrganizationalUnitIdParameter>]
[-Password <SecureString>] [-ResetPasswordOnNextLogon
<$true | $false>] [-SamAccountName <String>]
[-TemplateInstance <PSObject>] [-UseRusServer <String>]
[-WhatIf [<SwitchParameter>]]

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.

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.

Confirm

Optional

System.Management.Automation.SwitchParameter

The Confirm parameter causes the command to pause processing and requires you to acknowledge what the command will do before processing continues. You don't have to specify a value with the Confirm parameter.

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.

OrganizationalUnit

Optional

Microsoft.Exchange.Configuration.Tasks.OrganizationalUnitIdParameter

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

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.

UseRusServer

Optional

System.String

Note:
This parameter is available only in Exchange 2007 SP2.

The UseRusServer parameter instructs the command to use the specified Mailbox server on which the Address List service is running to obtain and then set mailbox and Active Directory user attributes.

The Address List service is a component in the Exchange System Attendant service. The Address List service creates and maintains Exchange-specific attribute values in Active Directory. You can use the Address List service to update recipient objects in a domain by using specific information, such as address list membership and e-mail addresses.

WhatIf

Optional

System.Management.Automation.SwitchParameter

The WhatIf parameter instructs the command to simulate the actions that it would take on the object. By using the WhatIf parameter, you can view what changes would occur without having to apply any of those changes. You don't have to specify a value with the WhatIf parameter.

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.

Note:
Managed custom folders are a premium feature of messaging records management (MRM). Mailboxes with policies that include managed custom folders require an Exchange Server Enterprise client access license (CAL).

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

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