Understanding Set-MailboxRegionalConfiguration in ExchangePowerShell

Administrators managing Microsoft Exchange Server or Exchange Online environments frequently need to adjust user mailbox settings. The Set-MailboxRegionalConfiguration cmdlet within ExchangePowerShell is the tool for modifying regional configurations such as language, time zone, and the formats used for dates and times. Proper configuration ensures a consistent user experience in Outlook and Outlook on the web (OWA) and correct behavior for features like resource mailbox booking restrictions.

You might need this cmdlet for several reasons:

• Standardizing regional settings across your organization.
• Correcting default settings, which often default to Pacific Standard Time, especially for non-user mailboxes like resource or shared mailboxes.
• Resolving configuration issues after mailbox migrations.
• Assisting individual users who encounter problems changing their settings.

While powerful, using Set-MailboxRegionalConfiguration requires care. Incorrect parameters, particularly mismatches between the selected language and the specified date or time formats, can lead to errors. This article guides you through understanding the cmdlet, troubleshooting common issues, applying solutions, and preventing future problems.

Troubleshooting Regional Configuration Issues

Before attempting changes, it’s wise to understand the current state and diagnose potential problems.

Connect to Exchange Online PowerShell

All commands discussed here require a connection to your Exchange environment via PowerShell. If you are managing Exchange Online (Microsoft 365), ensure you have the Exchange Online PowerShell module installed and connect using:

Connect-ExchangeOnline

For on-premises Exchange, open the Exchange Management Shell.

Check Current Mailbox Settings

Use the Get-MailboxRegionalConfiguration cmdlet to view the existing settings for a mailbox.

To check a single mailbox:
Replace "user@yourdomain.com" with the actual identity of the mailbox (like User Principal Name (UPN), email address, or Name).

Get-MailboxRegionalConfiguration -Identity "user@yourdomain.com"

This command returns the Language, DateFormat, TimeFormat, and TimeZone currently applied to the specified mailbox.

To check multiple or all mailboxes:
You can combine Get-Mailbox with Get-MailboxRegionalConfiguration.

# Check all user mailboxes
Get-Mailbox -RecipientTypeDetails UserMailbox -ResultSize Unlimited | Get-MailboxRegionalConfiguration

# Check a specific group or filter
Get-Mailbox -Filter "Department -eq 'Sales'" | Get-MailboxRegionalConfiguration

Identify the Mailbox Correctly

The -Identity parameter accepts various identifiers for the mailbox:

• User Principal Name (UPN): jane.doe@contoso.com
• Email Address: jane.doe@contoso.com
• Name: "Jane Doe" (use quotes if there are spaces)
• Alias: jdoe
• Distinguished Name (DN)
• GUID

Using the UPN is generally reliable.

Diagnosing the “DateFormat/TimeFormat isn’t valid” Error

A frequent error encountered when using Set-MailboxRegionalConfiguration is similar to:

Ex328A48|Microsoft.Exchange.Data.DataValidationException|DateFormat "dd/MM/yyyy" isn't valid for current language setting "en-US". Valid formats include "M/d/yyyy, M/d/yy, MM/dd/yy, MM/dd/yyyy, yy/MM/dd, yyyy-MM-dd, dd-MMM-yy".

Or:

Ex402B93|Microsoft.Exchange.Data.DataValidationException|The TimeFormat "h:mm tt" isn't valid for current language setting "da-DK". Valid formats include "HH:mm, H:mm".

This error means the string you provided for -DateFormat or -TimeFormat is not recognized as valid for the culture code specified in the -Language parameter (or the mailbox’s existing language if -Language wasn’t used in the command). Each language has a specific set of acceptable date and time patterns.

List Available Time Zones

The -TimeZone parameter requires a specific key name. To see the list of valid time zone names on a Windows system (which Exchange uses), run this command in PowerShell:

$TimeZone = Get-ChildItem "HKLM:\Software\Microsoft\Windows NT\CurrentVersion\Time zones" | foreach {Get-ItemProperty $_.PSPath}; $TimeZone | sort Display | Format-Table -Auto PSChildname,Display

The output displays a list. Use the value from the PSChildname column (e.g., “Pacific Standard Time”, “GMT Standard Time”, “W. Europe Standard Time”) as the input for the -TimeZone parameter. Enclose names with spaces in quotes.

Understand -LocalizeDefaultFolderName

Using the -LocalizeDefaultFolderName switch tells Exchange to rename the default mailbox folders (like Inbox, Sent Items, Drafts, Calendar, Contacts) to match the language specified by the -Language parameter in the same command. If you only change the language without this switch, the folder names remain in their previous language.

Solutions for Setting Mailbox Regional Configuration

Here are practical examples for applying regional settings.

Modifying a Single Mailbox

1. Change Only the Time Zone:
This is useful for correcting the default Pacific Standard Time often found on resource or shared mailboxes.

Set-MailboxRegionalConfiguration -Identity "conference.room1@yourdomain.com" -TimeZone "Central Europe Standard Time"

2. Change Language and Localize Folders:
This sets the mailbox language and renames default folders accordingly. Note that we omit DateFormat and TimeFormat here; they will either remain unchanged or might cause an error if incompatible with the new language. See solution 4 for the safer method.

# Example: Set language to German (Germany) and rename folders
Set-MailboxRegionalConfiguration -Identity "klaus.mueller@yourdomain.com" -Language "de-DE" -LocalizeDefaultFolderName

3. Change Language, Date Format, and Time Format Simultaneously:
If you know the exact valid formats for the target language, you can specify them.

# Example: Set language to French (France), use dd/MM/yyyy date, HH:mm time, and localize folders
Set-MailboxRegionalConfiguration -Identity "pierre.dubois@yourdomain.com" -Language "fr-FR" -DateFormat "dd/MM/yyyy" -TimeFormat "HH:mm" -LocalizeDefaultFolderName

Caution: This is prone to the “invalid format” error if your DateFormat or TimeFormat strings are incorrect for the fr-FR language setting.

4. Safely Change Language Using $null for Formats (Recommended):
This is the most robust way to change the language and avoid format errors. Setting DateFormat and TimeFormat to $null instructs Exchange to apply the default date and time formats associated with the specified language.

# Example: Set language to Spanish (Argentina), apply its default formats, and localize folders
Set-MailboxRegionalConfiguration -Identity "maria.garcia@yourdomain.com" -Language "es-AR" -DateFormat $null -TimeFormat $null -LocalizeDefaultFolderName

This approach avoids the need to research and specify exact format strings, significantly reducing the chance of errors.

Modifying Multiple Mailboxes via CSV

For applying changes to a list of users, using a CSV file is efficient.

1. Prepare the CSV File:
Create a simple text file named, for example, UsersToUpdate.csv. It needs a header row (e.g., UPN) followed by the User Principal Names of the mailboxes, one per line.

UPN
user1@yourdomain.com
user2@yourdomain.com
sharedmailbox@yourdomain.com

Save this file (e.g., in C:\temp\UsersToUpdate.csv). Ensure it uses UTF-8 encoding if dealing with international characters.

2. Script to Update Time Zone from CSV:

# Define the target Time Zone
$TargetTimeZone = "W. Australia Standard Time"

# Specify the path to your CSV file
$CsvPath = "C:\temp\UsersToUpdate.csv"

# Import users from CSV
$Users = Import-Csv -Path $CsvPath -Encoding UTF8

# Loop through each user and set the Time Zone
foreach ($User in $Users) {
    $MailboxUPN = $User.UPN
    Write-Host "Processing mailbox: $MailboxUPN"
    try {
        Set-MailboxRegionalConfiguration -Identity $MailboxUPN -TimeZone $TargetTimeZone -ErrorAction Stop
        Write-Host "Successfully updated Time Zone for $MailboxUPN" -ForegroundColor Green
    } catch {
        Write-Warning "Failed to update Time Zone for $MailboxUPN. Error: $($_.Exception.Message)"
    }
}

Write-Host "Script finished."

3. Script to Update Multiple Settings from CSV (using Splatting):
Splatting (@params) makes the command cleaner when setting multiple parameters. Remember to use $null for formats when changing language unless you are certain of compatibility.

# Define the desired regional settings
$RegionalSettings = @{
    TimeZone                  = "GMT Standard Time"
    Language                  = "en-GB"  # English (United Kingdom)
    DateFormat                = $null    # Use default date format for en-GB
    TimeFormat                = $null    # Use default time format for en-GB
    LocalizeDefaultFolderName = $true
}

# Specify the path to your CSV file
$CsvPath = "C:\temp\UsersToUpdate.csv"

# Import users from CSV
$Users = Import-Csv -Path $CsvPath -Encoding UTF8

# Loop through each user and apply the settings
foreach ($User in $Users) {
    $MailboxUPN = $User.UPN
    Write-Host "Processing mailbox: $MailboxUPN"
    try {
        # Apply settings using splatting
        Set-MailboxRegionalConfiguration -Identity $MailboxUPN @RegionalSettings -ErrorAction Stop
        Write-Host "Successfully updated regional settings for $MailboxUPN" -ForegroundColor Green
    } catch {
        Write-Warning "Failed to update regional settings for $MailboxUPN. Error: $($_.Exception.Message)"
    }
}

Write-Host "Script finished."

Modifying All Mailboxes (Bulk Update)

You can apply settings to all mailboxes, but exercise extreme caution.

1. Set Time Zone for All Mailboxes:

# !! CAUTION: This affects ALL mailboxes returned by Get-Mailbox !!
# Consider filtering Get-Mailbox first (e.g., -RecipientTypeDetails UserMailbox)
Get-Mailbox -ResultSize Unlimited | Set-MailboxRegionalConfiguration -TimeZone "Eastern Standard Time"

2. Set Multiple Settings for All Mailboxes (using Splatting):

# !! CAUTION: Affects ALL mailboxes. Test thoroughly first! !!
# Define the desired regional settings
$GlobalRegionalSettings = @{
    TimeZone                  = "AUS Eastern Standard Time"
    Language                  = "en-AU"  # English (Australia)
    DateFormat                = $null
    TimeFormat                = $null
    LocalizeDefaultFolderName = $true
}

# Apply settings to all mailboxes (consider filtering Get-Mailbox)
Get-Mailbox -ResultSize Unlimited | Set-MailboxRegionalConfiguration @GlobalRegionalSettings

Warning: Applying changes to all mailboxes carries significant risk. A mistake, especially with language and format settings, could impact every user or resource. Always test bulk commands on a small, non-critical group of mailboxes first.

Prevention and Best Practices

Follow these guidelines to avoid issues when managing mailbox regional settings:

• Use $null for Formats: When changing the -Language, always set -DateFormat $null and -TimeFormat $null unless you have verified the specific format strings are compatible with the target language. This is the single most effective way to prevent format validation errors.
• Verify Changes: After running Set-MailboxRegionalConfiguration, immediately use Get-MailboxRegionalConfiguration on one or more affected mailboxes to confirm the changes were applied as expected.
• Test Before Bulk Updates: Never run a bulk update (on all mailboxes or a large CSV list) without first testing the exact command or script on a single test mailbox or a small pilot group.
• Audit Regularly: Periodically check the regional settings of mailboxes, especially shared, resource, and service account mailboxes, as they often retain incorrect defaults set during creation. Exporting settings using Get-Mailbox -ResultSize Unlimited | Get-MailboxRegionalConfiguration | Export-Csv -Path "C:\temp\RegionalSettingsAudit.csv" -NoTypeInformation -Encoding UTF8 can help with auditing.
• User vs. Admin Control: Determine if your organization requires standardized settings enforced by administrators or if users can manage their own preferences via OWA settings (General -> Language and time). Clear communication helps manage user expectations.
• Double-Check Identity: Ensure you are targeting the correct mailbox by verifying the value used for the -Identity parameter.