New-MessageClassification

 

Applies to: Exchange Server 2007 SP1, Exchange Server 2007 SP2, Exchange Server 2007 SP3

Use the New-MessageClassification cmdlet to create a new message classification instance in your Exchange organization. After you create a new message classification, you can specify the message classification as a transport rule predicate. Before Microsoft Office Outlook 2007 and Outlook Web Access 2007 users can apply the message classification to messages, you must update the end-user systems with the message classification XML file that is created by the Export-OutlookClassification.ps1 script file. The Export-OutlookClassification.ps1 script file is located in the \Program Files\Microsoft\Exchange Server\Scripts directory.

When you create a new message classification, it has no locale. By default, the new message classification is used for all locales. After a default message classification is defined, you can add new locales of the classification by running the New-MessageClassification cmdlet and by specifying the default message classification identity that you want to localize.

Syntax

New-MessageClassification -Name <String> -DisplayName <String> -SenderDescription <String> [-ClassificationID <Guid>] [-Confirm [<SwitchParameter>]] [-DomainController <Fqdn>] [-RecipientDescription <String>] [-TemplateInstance <PSObject>] [-UserDisplayEnabled <$true | $false>] [-WhatIf [<SwitchParameter>]]

New-MessageClassification -Identity <MessageClassificationIdParameter> -Locale <CultureInfo> [-Confirm [<SwitchParameter>]] [-DisplayName <String>] [-DomainController <Fqdn>] [-RecipientDescription <String>] [-SenderDescription <String>] [-TemplateInstance <PSObject>] [-UserDisplayEnabled <$true | $false>] [-WhatIf [<SwitchParameter>]]

Detailed Description

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

  • Exchange Organization Administrator role

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

Parameters

Parameter Required Type Description

DisplayName

Required

System.String

Use the DisplayName parameter to specify the display name for the message classification instance. The display name appears in Office 2007 and is used by Outlook users to select the appropriate message classification before they send a message.

Note

The message classification XML file must be present on the sender's computer for the display name to be displayed.

If the UserDisplayEnabled parameter is set to $true, the display name is displayed for the recipient, even if no message classification XML file is installed.

When you specify a name that includes spaces, you must enclose the whole name in quotation marks, as follows, for example, "Display Name". The DisplayName parameter must contain 64 or fewer characters.

Identity

Required

Microsoft.Exchange.Configuration.Tasks.MessageClassificationIdParameter

Use this parameter to create a translated version of an existing message classification. You must also specify the Locale parameter. The Identity parameter can take a string value, which is the Name value of an existing message classification.

Locale

Required

System.Globalization.CultureInfo

Specifying a culture code for the Locale parameter creates a locale-specific version of the message classification. You must also pass the Identity parameter of the default existing message classification when you create a new locale-specific version.

Valid input for the Locale parameter are the string names that are listed in the Culture Name column in the Microsoft .NET Class Library class reference that is available at CultureInfo.

Name

Required

System.String

Use this parameter to specify the administrative name for the message classification instance. The name is used to administer the message classification instance. When you specify a name that includes spaces, you must enclose the whole name in quotation marks, as follows, for example, "Adminstrative Name". The Name parameter must contain 256 or fewer characters.

SenderDescription

Required

System.String

Use this parameter to explain to the sender what the message classification is intended to achieve. The text that you enter in this parameter is used by Outlook users to select the appropriate message classification before they send a message. Enclose the description in quotation marks, as follows, for example, "This is the sender description that explains when to use this message classification". The SenderDescription parameter must contain 1024 or fewer characters.

ClassificationID

Optional

System.Guid

Use this parameter to specify a classification ID of an existing message classification that you want to import and use in your Exchange organization. Use this parameter if you are configuring message classifications that span two Exchange forests in the same enterprise.

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.

DomainController

Optional

Microsoft.Exchange.Data.Fqdn

To specify the fully qualified domain name of the domain controller that writes this configuration change to the Active Directory directory service, include the DomainController parameter on the command. The DomainController parameter is not supported on computers that have the Edge Transport server role installed. The Edge Transport server role only writes to and reads from the local Active Directory Application Mode (ADAM) instance.

RecipientDescription

Optional

System.String

Use this parameter to explain to the recipient what the message classification was intended to achieve. The text that you enter in this parameter is viewed by Outlook users when they receive a message that has this message classification. Enclose the description in quotation marks, as follows, for example, "This is the recipient description that explains how to treat the message that has been classified". The RecipientDescription parameter must contain 1024 or fewer characters.

If you do not enter a value for this parameter, the description that you enter for SenderDescription is used.

TemplateInstance

Optional

System.Management.Automation.PSObject

When an existing object is supplied to the TemplateInstance parameter, the command uses the configuration of that object to create an identical copy of the object on a local or target server.

UserDisplayEnabled

Optional

System.Boolean

Use this parameter to specify whether the values that you entered for the DisplayName and RecipientDescription parameters are displayed in the recipient's Outlook message.

If you set the UserDisplayEnabled parameter to $false, messages that are sent to recipients and that have this message classification do not display any classification information.

The default value is $true.

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.

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.

Example

The following code sample shows three examples that use the New-MessageClassification cmdlet.

The first example shows the New-MessageClassification command that has the required parameters.

The second example shows how to create a locale-specific (Spanish - Spain) version of an existing message classification.

The third example shows how to create another locale-specific (Spanish - Mexico) version of an existing message classification.

New-MessageClassification -Name Example -DisplayName "New Message Classification" -SenderDescription "This is the description text"
New-MessageClassification -Identity Example -Locale es-ES -DisplayName "España Example " -SenderDescription "Este es el texto de la descripción"
New-MessageClassification -Identity Example -Locale es-MX -DisplayName "México Example" -SenderDescription "Este es el texto de la descripción"