Applies to: Exchange Server 2013

Topic Last Modified: 2012-07-23

Use the New-RemoteMailbox cmdlet to create a mail-enabled user in the on-premises Active Directory and also create an associated mailbox in the cloud-based service.

For information about the parameter sets in the Syntax section below, see Syntax.

Syntax

New-RemoteMailbox -Room <SwitchParameter> [-Password <SecureString>] [-UserPrincipalName <String>] <COMMON PARAMETERS>
New-RemoteMailbox -Equipment <SwitchParameter> [-Password <SecureString>] [-UserPrincipalName <String>] <COMMON PARAMETERS>
New-RemoteMailbox -AccountDisabled <SwitchParameter> [-Password <SecureString>] [-UserPrincipalName <String>] <COMMON PARAMETERS>
New-RemoteMailbox [-Password <SecureString>] [-UserPrincipalName <String>] <COMMON PARAMETERS>
New-RemoteMailbox -Password <SecureString> -UserPrincipalName <String> <COMMON PARAMETERS>
COMMON PARAMETERS: -Name <String> [-Alias <String>] [-ArbitrationMailbox <MailboxIdParameter>] [-Archive <SwitchParameter>] [-Confirm [<SwitchParameter>]] [-DisplayName <String>] [-DomainController <Fqdn>] [-FirstName <String>] [-ImmutableId <String>] [-Initials <String>] [-LastName <String>] [-ModeratedBy <MultiValuedProperty>] [-ModerationEnabled <$true | $false>] [-OnPremisesOrganizationalUnit <OrganizationalUnitIdParameter>] [-OverrideRecipientQuotas <SwitchParameter>] [-PrimarySmtpAddress <SmtpAddress>] [-RemotePowerShellEnabled <$true | $false>] [-RemoteRoutingAddress <ProxyAddress>] [-ResetPasswordOnNextLogon <$true | $false>] [-SamAccountName <String>] [-SendModerationNotifications <Never | Internal | Always>] [-WhatIf [<SwitchParameter>]]

Examples

EXAMPLE 1

This example creates an on-premises mail-enabled user and its associated mailbox in the service. The remote routing address doesn't need to be specified because mail flow between the on-premises organization and the service has been configured. Using this configuration, the New-RemoteMailbox cmdlet automatically calculates the SMTP address of the mailbox to be used with the RemoteRoutingAddress parameter. This example also assumes directory synchronization has been configured.

First, store the password to use with the new remote mailbox in a variable by using the Get-Credential cmdlet.

Copy Code 
$Credentials = Get-Credential

Then run the New-RemoteMailbox cmdlet to create the mail user.

Copy Code 
New-RemoteMailbox -Name "Kim Akers" -Password $Credentials.Password -UserPrincipalName kim@contoso.com

After the new mail user is created, directory synchronization synchronizes the new mail user to the service and the associated mailbox is created.

EXAMPLE 2

This example shows how to do the following:

  • Creates an on-premises mail-enabled user. The mail-enabled user is placed in the contoso.com/Archive Users OU. The OU has no effect on the mailbox in the service.

  • Creates the associated mailbox in the service.

  • Creates an archive mailbox in the service for the mailbox.

As in Example 1, this example assumes that mail flow and directory synchronization have been properly configured.

First, store the password to use with the new remote mailbox in a variable by using the Get-Credential cmdlet.

Copy Code 
$Credentials = Get-Credential

Then run the New-RemoteMailbox cmdlet to create the mail user.

Copy Code 
New-RemoteMailbox -Name "Kim Akers" -Password $Credentials.Password -UserPrincipalName kim@contoso.com -OnPremisesOrganizationalUnit "contoso.com/Archive Users" -Archive

Detailed Description

The New-RemoteMailbox cmdlet creates an on-premises mail-enabled user. The mail-enabled user contains a specific attribute, which indicates that an associated mailbox in the service should be created when the user is synchronized to the service using directory synchronization.

Directory synchronization must be configured correctly for a mailbox to be created in the service. Creation of the mailbox in the service isn't immediate and depends on the directory synchronization schedule.

Important:
The policies that you apply to recipients in the on-premises Exchange organization, such as Unified Messaging or compliance policies, aren't applied to mailboxes in the service. You must configure policies in the service if you want policies to be applied to recipients in the service.

You need to be assigned permissions before you can run this cmdlet. Although all parameters for this cmdlet are listed in this topic, you may not have access to some parameters if they're not included in the permissions assigned to you. To see what permissions you need, see the "Remote mailboxes" entry in the Recipients Permissions topic.

Parameters

Parameter Required Type Description

AccountDisabled

Required

System.Management.Automation.SwitchParameter

The AccountDisabled switch specifies whether to create the mail-enabled user in a disabled state. You don't have to specify a value with this parameter.

Equipment

Required

System.Management.Automation.SwitchParameter

The Equipment switch specifies that the mailbox in the service should be created as an equipment resource mailbox.

You can't use the Equipment switch if you specified the Room switch.

Name

Required

System.String

The Name parameter specifies the common name (CN) of the on-premises mail-enabled user and its associated mailbox in the service.

Password

Required

System.Security.SecureString

The Password parameter specifies the password used by the mail user to secure his or her account and associated mailbox in the service.

Room

Required

System.Management.Automation.SwitchParameter

The Room switch specifies that the mailbox in the service should be created as a room resource mailbox.

You can't use the Room switch if you specified the Equipment switch.

UserPrincipalName

Required

System.String

The UserPrincipalName parameter defines the name of a system user in an email address format (for example, ed@contoso.com).

Alias

Optional

System.String

The Alias parameter specifies the email alias of the user and its associated mailbox in the service that you're creating.

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

ArbitrationMailbox

Optional

Microsoft.Exchange.Configuration.Tasks.MailboxIdParameter

The ArbitrationMailbox parameter specifies the mailbox used to manage the moderation process.

Archive

Optional

System.Management.Automation.SwitchParameter

The Archive switch specifies whether to create an archive mailbox in the service in addition to the mailbox that's created in the service.

You don't have to specify a value with this switch.

Confirm

Optional

System.Management.Automation.SwitchParameter

The Confirm switch 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 switch.

DisplayName

Optional

System.String

The DisplayName parameter specifies the name displayed in Microsoft Outlook for the mail user and its associated mailbox in the service.

DomainController

Optional

Microsoft.Exchange.Data.Fqdn

The DomainController parameter specifies the fully qualified domain name (FQDN) of the domain controller that writes this configuration change to Active Directory.

FirstName

Optional

System.String

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

ImmutableId

Optional

System.String

The ImmutableId parameter is used by GAL Synchronization (GALSync) and specifies a unique and immutable identifier in the form of an SMTP address for an Exchange mailbox that's used for federated delegation when requesting Security Assertion Markup Language (SAML) tokens. If federation is configured for this mailbox and you don't set this parameter when you create the mailbox, Exchange creates the value for the immutable identifier based upon the mailbox's ExchangeGUID and the federated account namespace, for example, 7a78e7c8-620e-4d85-99d3-c90d90f29699@mail.contoso.com. You must set the ImmutableId parameter if Active Directory Federation Services (AD FS) is deployed to allow single sign-on into an off-premises mailbox and AD FS is configured to use a different attribute than ExchangeGUID for sign-on token requests. Both, Exchange and AD FS must request the same token for the same user to ensure proper functionality for a cross-premise Exchange deployment scenario.

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.

ModeratedBy

Optional

Microsoft.Exchange.Data.MultiValuedProperty

The ModeratedBy parameter specifies the users responsible for moderating the messages sent to this mail user and its associated mailbox in the service. To designate more than one user, separate the users with commas.

This parameter is required if you set the ModerationEnabled parameter to $true.

ModerationEnabled

Optional

System.Boolean

The ModerationEnabled parameter specifies whether to enable or disable moderation for the mail user. The two possible values for this parameter are $true or $false. To enable moderation, set this parameter to $true. To disable moderation, set this parameter to $false.

The default value is $false.

OnPremisesOrganizationalUnit

Optional

Microsoft.Exchange.Configuration.Tasks.OrganizationalUnitIdParameter

The OnPremisesOrganizationalUnit parameter specifies the organizational unit (OU) in the on-premises organization in which the new mailbox is added (for example, redmond.contoso.com/Users).

This parameter has no effect on the mailbox in the service.

OverrideRecipientQuotas

Optional

System.Management.Automation.SwitchParameter

This parameter is reserved for internal Microsoft use.

PrimarySmtpAddress

Optional

Microsoft.Exchange.Data.SmtpAddress

The PrimarySmtpAddress parameter specifies the primary SMTP address for the mail user. By default, the primary SMTP address is generated based on the default email address policy. If you specify a primary SMTP address by using this parameter, the command sets the EmailAddressPolicyEnabled attribute of the mail user to $false, and the email addresses of this mail user aren't automatically updated based on email address policies.

RemotePowerShellEnabled

Optional

System.Boolean

The RemotePowerShellEnabled parameter specifies whether the user can use remote Windows PowerShell. Remote Windows PowerShell is required to open the Exchange Management Shell on Mailbox and Client Access servers. Access to remote Windows PowerShell is required even if you're trying to open the Shell on the local server.

The valid values are $True and $False. The default value is $True.

RemoteRoutingAddress

Optional

Microsoft.Exchange.Data.ProxyAddress

The RemoteRoutingAddress parameter specifies the SMTP address of the mailbox in the service that this user is associated with.

If you've configured mail flow between the on-premises organization and the service, you don't need to specify this parameter. The remote routing address is calculated automatically.

ResetPasswordOnNextLogon

Optional

System.Boolean

The ResetPasswordOnNextLogon parameter specifies whether the password in the Password parameter must be reset the next time the user logs on. 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 defines the logon name used to support clients and servers running older versions of the operating system. This attribute must contain fewer than 20 characters. An account name can contain letters, numbers, and the following punctuation marks and symbols:

  • !

  • #

  • $

  • %

  • ^

  • &

  • -

  • .

  • _

  • {

  • }

  • |

  • ~

SendModerationNotifications

Optional

Microsoft.Exchange.Data.Directory.Recipient.TransportModerationNotificationFlags

The SendModerationNotifications parameter specifies whether status notifications are sent to users when they send a message to the moderated distribution group. You can specify one of the following values:

  • Always

  • Internal

  • Never

Set this parameter to Always if you want notifications to be sent to all senders.

Set this parameter to Internal if you want notifications to be sent only to the senders who are internal to your organization.

Set this parameter to Never to disable all status notifications.

The default value is Never.

Note:
The sender is always notified if the message is rejected by the moderators, regardless of the value of this parameter.

WhatIf

Optional

System.Management.Automation.SwitchParameter

The WhatIf switch instructs the command to simulate the actions that it would take on the object. By using the WhatIf switch, 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 switch.

Input Types

To see the input types that this cmdlet accepts, see Cmdlet Input and Output Types. If the Input Type field for a cmdlet is blank, the cmdlet doesn’t accept input data.

Return Types

To see the return types, which are also known as output types, that this cmdlet accepts, see Cmdlet Input and Output Types. If the Output Type field is blank, the cmdlet doesn’t return data.