The Set-Mailbox Cmdlet in PowerShell
The Set-Mailbox command-let enables IT administrators to modify the settings of a mailbox. It enables them to change the common attributes of a mailbox, such as:
- User’s name
- Display name
- Alias
- User logon name
- Title
- Department
- Company
Moreover, it also allows you to change uncommon attributes, such as:
- Arbitration
- ArbitrationMailbox
- AttributesToClear
- ArchiveDatabase
Read More: Preventing Get-ADUser Not Recognized Error
Table Of Contents
-
The Set-Mailbox Cmdlet in PowerShell
-
Set-Mailbox Cmdlet Parameters
-
Set-Mailbox Cmdlet Examples
-
Change the Alias of a Mailbox
-
Update the Display Name of a Mailbox
-
Update the samAccountName of a Mailbox
-
Set Up Arbitration Mailbox
-
Set Up an Archive Database for a Mailbox
-
Set Up a Database for a Mailbox
-
Set Up Archive Quota for a Mailbox
-
Set Archive Warning Quota for a Mailbox
-
Setting Forwarding Address for a Mailbox
-
Forwarding SMTP Address
-
Deliver to Mailbox and Forward
-
Change Multiple Mailboxes at Once
-
When it comes to modifying or updating mailbox settings, Microsoft provides an easy-to-use web-based interface called Exchange Administration Center (formerly Exchange Management Console). However, you can only manage a handful of settings from it, leaving room for a more powerful tool that can update almost all the settings for a mailbox. Microsoft provides that kind of a tool too, called Microsoft PowerShell (Exchange Management Shell to be exact).
Through Exchange Management Shell, you can use multiple command-lets (for example, Get-Mailbox, Set-Mailbox, Get-ADUser) with many parameters to update settings that you cannot otherwise manage using EAC (Exchange Administration Center).
In this blog, we will focus more on the uncommon attributes. Most administrators prefer to update mailbox attributes using PowerShell because PowerShell enables them to update multiple mailboxes at once or change some settings at the organizational level.
The Set-Mailbox command-let is available for:
- Microsoft Exchange Server, which is an on-premises Exchange server
- Exchange Online (Microsoft 365)
Set-Mailbox Cmdlet Parameters
Before elaborating the technical aspects of the command-let, which are often used for complex settings, let’s look at some of the common parameters.
Identity Parameter
The Identity parameter is available for most of the PowerShell command-lets and is used to fetch the user object or multiple user objects on which you want to perform the relevant actions. You can use many types of values with this parameter, but the most common ones are:
- Mailbox Name
- Email Address
- Security Account Manager name (SamAccountName)
- Security Identifier (SID)
- Distinguished Name (DN)
- Globally Unique Identifier (GUID)
You can also use a local user object variable for collecting multiple user objects and use that variable to pass a user object through the pipeline for the identity parameter in a PowerShell script. Hence, we elaborate on local user object variable as follows:
Set-Mailbox Cmdlet Examples
The Set-Mailbox cmdlet is be used to update the display name of a mailbox, set up an archive database for a mailbox, and more.
Change the Alias of a Mailbox
The -Alias parameter specifies the recipient’s Exchange alias (also known as a mail nickname). This value distinguishes the receiver as a mail-enabled object, and it should not be confused with several email addresses for the same person (also known as proxy addresses). Only one alias value can be assigned to a recipient. The maximum character length is 64.
The alias value is used to produce the primary email address (alias@domain.com) when you establish a recipient without specifying an email address. The syntax for setting up an alias value is as follows.
Syntax:
Set-Mailbox -Identity "AbbeyCrawford" -Alias "AbbeyCrawford2"
This command-let will update the alias for the user named Abbey Crawford to AbbeyCrawford2.
Update the Display Name of a Mailbox
The -DisplayName parameter is used to update the display name of a mailbox. The display name is shown in the mailbox properties in Exchange Admin Center, as well as in the address list and in the Outlook email client. The maximum length of display name attribute is 256 characters. If you want to use spaces in display name, use quotation marks (“”) in the value for this parameter.
Syntax:
Set-Mailbox -Identity “AbbeyWarren” -DisplayName “Abbey Eckels”
Update the samAccountName of a Mailbox
You can use the -samAccountName parameter only with on-premises Exchange Server.
SamAccountName (also known as the user account or group name used before Windows 2000) is used as an object identifier that is used with Pre-Windows 2000 clients and server OS. The following characters are allowed in the value:
- Letters
- Numbers
- Spaces
- Periods (.)
- Exclamation Mark (!)
- Hash (#)
- Ampersand (&)
- Percent (%)
- Dash (-)
- Underscore (_)
A period cannot be the final character. Unicode characters are acceptable, however accented characters (for example, o and ö) may cause collisions. The maximum character length is 20.
Syntax:
Set-Mailbox -Identity “AbbeyCrawford” -samAccountName abbeyeckels
Set-Up Arbitration Mailbox
Arbitration mailboxes are used to store many forms of system data and to manage the messaging approval process. There are seven arbitration mailboxes included in Exchange 2016 CU8 or later Exchange versions.
The Arbitration parameter is used to modify the arbitration mailboxes. This parameter does not require a value to be specified.
This parameter should not be used to modify arbitration mailboxes that are used to store audit log settings or data. Use the AuditLog or AuxAuditLog switches instead.
You can use this parameter only with on-premises Exchange Server.
Syntax:
- Run the following commands to re-create the arbitration mailbox, Migration.8f3e7716-2011-43e4-96b1-aba62d229136.
Enable-Mailbox -Identity "Migration.8f3e7716-2011-43e4-96b1-aba62d229136" -Arbitration
- Run the following command to set the Persisted Capabilities (msExchCapabilityIdentifiers) for the mailbox.
Set-Mailbox -Identity "Migration.8f3e7716-2011-43e4-96b1-aba62d229136" -Arbitration -Management $true -Force
Set-Up an Archive Database for a Mailbox
The -ArchiveDatabase parameter is used to update the Exchange database that contains the archive associated with this mailbox. You can use any of the following values, e.g., Name, Distinguished Name (DN) and GUID, that uniquely identify the database.
You can use this parameter only with on-premises Exchange Server.
Syntax:
Set-Mailbox -Identity “AbbeyCrawford” -ArchiveDatabase Archive
Set-Up a Database for a Mailbox
The -Database parameter is used to assign the mailbox database for a user. You can use any of the following values, e.g., Name, Distinguished Name (DN) and GUID, that uniquely identify the database.
You can use this parameter only with on-premises Exchange Server.
Syntax:
Set-Mailbox -Identity “AbbeyCrawford” -Database Marketing
Set-Up Archive Quota for a Mailbox
You can use the -ArchiveQuota parameter to specify the maximum size for the archive mailbox of a user. If the size of the archive mailbox exceeds or reaches, the user cannot accept further messages. You can provide a valid value in numbers between bytes to terabytes or an unlimited value. When specifying a value for this parameter, you can use:
- B (bytes)
- KB (kilobytes)
- MB (megabytes)
- GB (gigabytes)
- TB (terabytes)
You can use this parameter only with on-premises Exchange Server.
Syntax:
Set-Mailbox -Identity “AbbeyCrawford” -ArchiveQuota 50GB
For archive quota details, you can see the output of this command-let by opening the mailbox properties of a user.
Set Archive Warning Quota for a Mailbox
The -ArchiveWarningQuota parameter defines the size of the user’s archive mailbox warning threshold. The user receives a descriptive warning message if the archive mailbox approaches or surpasses this size. You can provide a valid value in numbers between bytes to terabytes or an unlimited value. When you specify the value for this parameter, you can use:
- B (bytes)
- KB (kilobytes)
- MB (megabytes)
- GB (gigabytes)
- TB (terabytes)
You can use this parameter only with on-premises Exchange Server.
The value of ‘Archive Warning Quota’ must be less than or equal to the value of ‘Archive Quota’.
Syntax:
Set-Mailbox -Identity “AbbeyCrawford” -ArchiveQuota 45GB
For archive quota warning details, you can see the output of this command-let by opening the mailbox properties of a user.
Setting Forwarding Address for a Mailbox
Use the -ForwardingAddress parameter to specify a forwarding email address in your company for the messages sent to any mailbox. Examples of some unique identifiers that can be used for the internal email recipient are:
- Name
- Alias
- Distinguished Name (DN)
- Email Address
- GUID
There is another related parameter “DeliverToMailboxAndForwar”, that controls how messages are delivered and forwarded. Default value is null, which means that forwarding is not enabled. However,
- If “DeliverToMailboxAndForward” is enabled, messages can be delivered to the mailbox and forwarded email address.
- If “DeliverToMailboxAndForward” is disabled, message can only be delivered to the forwarded email recipient, but not to the original mailbox.
Syntax:
Set-Mailbox -Identity “AbbeyCrawford” -ForwardingAddress “AbbeyEckels”
You can see the forwarding email address in the mailbox properties of a user, using Exchange Administration Center, as shown below:
Forwarding SMTP Address
The -ForwardingSmtpAddress parameter is used to specify the mailbox for the messages sent to that respective mailbox. This parameter is used for external non-validated email addresses.
If you use both ForwardingAddress and ForwardingSMTPAddress, the value for latter will be ignored and messages will only be forwarded to the recipient provided by the ForwardingAddress parameter.
Syntax:
Set-Mailbox -Identity “AbbeyCrawford” -ForwardingSmtpAddress “test@google.com”
Notice the warning in the figure. When you run the command-let to set a forwarding SMTP address, it clearly states that you must first disable the forwarding for the mailbox; then these changes will take effect. So now, disable forwarding for the mailbox, which means that DeliverToMailboxAndForwarding should be disabled. Then run the above command-let and you will notice that changes already took place after disabling the DeliverToMailboxAndForwarding option.
Now you can run the following command-let to check the status of all forwarding options:
Get-Mailbox AbbeyCrawford : FL DeliverToMailboxAndForward,ForwardingAddress,ForwardingSmtpAddress
To further confirm this scenario, you can run the Set-Mailbox command-let to set the forwarding address again, and you will see a warning message that the forwarding SMTP address is already in place and will be overwritten.
Deliver to Mailbox and Forward
As discussed in the Forwarding Address section, this parameter is used when you want to forward the message sent to the mailbox to the forwarding address as well as to the respective mailbox. You can use either the “Forwarding Address” or the “Forwarding SMTP Address” parameter with the Deliver to mailbox and forward parameter.
This parameter takes values in Boolean type, if $true is provided, messages will be delivered to the forwarded recipient and to the mailbox, if value is $false, then messages will only be delivered to forwarded recipient.
Syntax:
Set-Mailbox -Identity “AbbeyCrawford” -ForwardingAddress “AbbeyEckels” -DeliverToMailBoxAndForward $True
Use the following command-let to see the details of the forwarding settings:
Get-Mailbox AbbeyCrawford | FL DeliverToMailboxAndForward,ForwardingAddress,ForwardingSmtpAddress
Change Multiple Mailboxes at Once
We can pipe cmdlets one after another in PowerShell. So, if you need to change a property on several mailboxes, first apply a filter to get all the users, then use the set-mailbox cmdlet to edit the mailboxes.
To get all employees with the department “HR”, we first filter the Get-ADUser command-let and then update each user’s mailbox attributes, or multiple attributes. I will use this command-let to set the forwarding for each mailbox.
Syntax:
Get-AdUser -Filter {department eq 'HR'} | ForEach {Set-Mailbox -Identity $_.Name -DeliverToMailboxAndForward $true -ForwardingAddress "AbbeyCrawford"}
But before we use the above command-let, let’s first use the first part of the command-let and see the results coming over.
Get-ADUser -Filter {department eq 'HR'} | ft
Now when you run the Set-Mailbox command-let combined with a “For” loop to set the forwarding for multiple mailboxes related to the HR department, the command runs successfully but does not show you any output – but if there aren’t any errors, then changes are applied successfully. You can see them in Exchange Administration Center.
Jonathan Blackwell
View ProfileSince 2012, Jonathan Blackwell, an engineer and innovator, has provided engineering leadership that has put GroupID at the forefront of group and user management for Active Directory and Azure AD environments. His experience in development, marketing, and sales allows Jonathan to fully understand the Identity market and how buyers think.