How to Import Address Rewrite Entries
Microsoft Exchange Server 2007 will reach end of support on April 11, 2017. To stay supported, you will need to upgrade. For more information, see Resources to help you upgrade your Office 2007 servers and clients.
Applies to: Exchange Server 2007, Exchange Server 2007 SP1, Exchange Server 2007 SP2, Exchange Server 2007 SP3
This topic explains how to use the Exchange Management Shell to import address rewrite entries into a computer that has the Microsoft Exchange Server 2007 Edge Transport server role installed.
You can use the Exchange Management Shell to perform bulk imports of address rewrite entries on an Edge Transport server. The following are some of the common scenarios in which you may want to perform a bulk import of address rewrite entries:
Migration You may want to bulk import address rewrite entries from a previous solution that is being replaced by an Edge Transport server solution.
Outsourcing You may have to bulk import address rewrite entries when you enter into agreements with third-party solution providers where their e-mail addresses must be rewritten.
Acquisition You may have to bulk import address rewrite entries when the acquisition of other organizations requires the interim rewriting of the e-mail addresses of the acquired organizations.
If you have more than one Edge Transport server, we recommend that you use the following procedures to import address rewrite entries into a single Edge Transport server, and then clone the configuration of that Edge Transport server to other Edge Transport servers in your organization.
For more information about how to clone an Edge Transport server, see Using Edge Transport Server Cloned Configuration.
Before You Begin
To perform the following procedures on a computer that has the Edge Transport server role installed, you must log on by using an account that is a member of the local Administrators group on that computer.
You must be familiar with how to create an address rewrite entry before you try to use comma-separated value (CSV) files to perform bulk imports of address rewrite entries. For information about how to create an address rewrite entry, see How to Create a New Address Rewrite Entry.
Procedure
The following sections help you understand how to import address rewrite entries by using CSV files:
Creating a CSV File This section describes the required and optional fields in a CSV file that can be used to import address rewrite entries. The section also describes the specific requirements when you use the ExceptionList and OutboundOnly parameters in the CSV file.
Understanding How CSV Files Are Used with the New-AddressRewriteEntry Cmdlet This section explains how the Exchange Management Shell formats and then uses the data that is contained in the CSV file to import address rewrite entries.
Importing a CSV File to Create Multiple Address Rewrite Entries This section builds on the information in the previous sections with instructions about how to use the Exchange Management Shell commands that are required to import a CSV file and use it to create multiple address rewrite entries.
Creating a CSV File
First, you must create a CSV file that contains columns of values that correlate to the parameters that are required by the New-AddressRewriteEntry cmdlet. The following values are required by the New-AddressRewriteEntry cmdlet and therefore must have corresponding columns in the CSV file:
Name This parameter must be a string that uniquely identifies the address rewrite entry.
InternalEmailAddress This parameter specifies the internal Simple Mail Transfer Protocol (SMTP) address to be rewritten.
ExternalEmailAddress This parameter specifies the external SMTP address to be rewritten.
The following parameters are optional. You can include columns for them in the CSV file if you need them:
ExceptionList This parameter specifies the list of subdomains that should not be rewritten. No SMTP addresses contained within the specified subdomains are rewritten.
OutboundOnly This parameter specifies whether the address rewrite entry should rewrite SMTP addresses on messages that are inbound and outbound to the Exchange 2007 organization, or rewrite only those messages that are outbound from the Exchange 2007 organization.
If you specify values for the ExceptionList and OutboundOnly columns in the CSV file, every row must include a value in that column. For example, if you specify a value for the ExceptionList column in any row of the CSV file, all other rows in the CSV file must also contain a value in that column. This is because the ExceptionList parameter on the command line expects a value from the CSV file.
For more information about each parameter in these lists, see New-AddressRewriteEntry.
Specific Requirements When You Include the ExceptionList Parameter in a CSV File
If you want to create multiple address rewrite entries where some entries require values for the ExceptionList parameter and some entries do not, you must separate those address rewrite entries and create separate CSV files, and then import each of those CSV files. Also, you must enclose the values that are used with the ExceptionList parameter in double quotation marks ("). If you want to specify multiple domains that have the ExceptionList parameter, you must separate each value by using commas (,). For example, the string "domain1.com,domain2.com, domain3.com" contains three domains enclosed with double quotation marks and separated by commas.
Specific Requirements When You Include the OutboundOnly Parameter in a CSV File
If you specify values in the OutboundOnly column in one row of the CSV file, you must specify a value in the OutboundOnly column in every other row in the CSV file, just as with the ExceptionList parameter. However you can easily manage this requirement by specifying whether the OutboundOnly parameter should be True or False in each row.
Unlike Boolean usage elsewhere in the Exchange Management Shell, when you specify a value for the OutboundOnly parameter in a CSV file, you must specify a value of True or False, not $True or $False. This is because the value in the CSV file is manually converted to a Boolean value when the CSV file is interpreted on the command line.
For more information about when you must use the OutboundOnly parameter and how to use the OutboundOnly parameter, see the "Considerations for Use of Outbound-Only Address Rewriting" section in Planning for Address Rewriting.
Example of a CSV File with Optional Parameters Populated
The following example shows how a CSV file can be populated with the optional ExceptionList and OutboundOnly parameters included:
Name,InternalAddress,ExternalAddress,ExceptionList,OutboundOnly
"Wingtip UK", *.wingtiptoys.co.uk, tailspintoys.com,"legal.wingtiptoys.co.uk,finance.wingtiptoys.co.uk,support.wingtiptoys.co.uk",True
"Wingtip USA", *.wingtiptoys.com, tailspintoys.com,"legal.wingtiptoys.com,finance.wingtiptoys.com,support.wingtiptoys.com,corp.wingtiptoys.com",True
"Wingtip Canada", *.wingtiptoys.ca, tailspintoys.com,"legal.wingtiptoys.ca,finance.wingtiptoys.ca,support.wingtiptoys.ca",True
The following example shows how a CSV file can be populated with the optional OutboundOnly parameter included:
Name,InternalAddress,ExternalAddress,OutboundOnly
"Contoso Sales",*.sales.contoso.com,contoso.com,True
"Contoso Research",*.research.contoso.com,contoso.com,True
"Contoso UK",*.contoso.co.uk,contoso.com,True
"Contoso Japan",*.contoso.co.jp,contoso.com,True
"Contoso Support",support@adatum.com,support@contoso.com,False
"Contoso Financial External",contosofinancial@woodgrovebank.com,financialinqueries@contoso.com,False
Understanding How CSV Files Are Used with the New-AddressRewriteEntry Cmdlet
To import address rewrite entries by using CSV files, you must use the Import-Csv cmdlet. The Import-Csv cmdlet reads the CSV file and outputs each row in the CSV file as an array element and each column in the row as a property of that array element. You can see how this works by using the CSV file in "Example of a CSV File with Optional Parameters Populated" earlier in this topic. Import the example CSV file by using the following command, after you copy the text in the example into a file that is named example.csv:
$CsvContents = Import-Csv c:\example.csv
Then, type the following command on the command line:
$CsvContents
The following data is returned:
Name InternalAddress ExternalAddress OutboundOnly
---- --------------- --------------- ------------
Contoso Sales *.sales.contoso.com contoso.com True
Contoso Research *.research.conto... contoso.com True
Contoso UK *.contoso.co.uk contoso.com True
Contoso Japan *.contoso.co.jp contoso.com True
Contoso Support support@adatum.com support@contoso.com False
Contoso Financia... contosofinancial... financialinqueri... False
If you want to view only the value that is contained in the InternalAddress column of the third row, you can use the following command:
$CsvContents[2].InternalAddress
This returns the value *.contoso.co.uk.
Note
Arrays always start at 0. Therefore, to retrieve the values from the third row, you must specify array element 2. For more information about arrays, see Arrays.
Understanding this example will make it easier for you to understand how the Exchange Management Shell processes the CSV file and uses it to pass data to the New-AddressRewriteEntry cmdlet.
As you can see in this example, each row in the CSV file becomes an array element, and each column becomes a property of that array element. By using the ForEach cmdlet, the Exchange Management Shell can move through the array automatically from start to finish and perform actions as each array element, in this case, one row from the CSV file, is encountered. After an array element has been passed to the ForEach cmdlet in the pipeline, the Exchange Management Shell can then access the properties that are stored within it. In this case, the properties are the columns that are contained on each row.
You can then use these properties to construct the New-AddressRewiteEntry command that is required to create address rewrite entries. The properties are named by using the column headings in the CSV file. They do not have to match the parameter name on the cmdlet. The following command is constructed from the explanation of this example:
Import-Csv c:\example.csv | ForEach { New-AddressRewriteEntry -Name $_.Name -InternalAddress $_.InternalAddress -ExternalAddress $_.ExternalAddress -OutboundOnly ([Bool]::Parse($_.OutboundOnly)) -ExceptionList ($_.ExceptionList.Split(","))}
Note
You don't have to assign an imported CSV file to a variable as was shown in the example at the beginning of this section. You can just include the Import-Csv cmdlet and pipe the output of that cmdlet to the ForEach cmdlet as shown in this example.
This command loops through each row in the example.csv file, and then uses the New-AddressRewriteEntry cmdlet to create address rewrite entries by using the parameter values obtained from the columns that exist in each row.
You probably noticed the $_ special variable in this command. The $_ special variable instructs the command to examine the current object in the pipeline. In this case, that is the current row of the CSV file.
The OutboundOnly and ExceptionList properties also have additional text surrounding their respective properties. The text ([Bool]::Parse($_.OutboundOnly)) instructs the Exchange Management Shell to interpret the string that is contained within the OutboundOnly property as a Boolean value. The text ($_.ExceptionList.Split(",")) instructs the Exchange Management Shell to split multiple values that are contained within the ExceptionList property by using commas. Without the text surrounding the ExceptionList property, the values that are contained in the ExceptionList property are treated as a single string, even if commas are present.
For more information about pipelining, see Pipelining.
Importing a CSV File to Create Multiple Address Rewrite Entries
Now that you understand what is going on behind the scenes, you can create a CSV file and use it to create multiple address rewrite entries. Create the CSV file that has at least the Name, InternalAddress, and ExternalAddress columns. If you want to specify values for the ExternalAddress and OutboundOnly parameters, add those columns also. Remember that every row must have a value in every column. For an example of a suitably formatted CSV file, see the examples in "Example of a CSV File with Optional Parameters Populated" earlier in this topic.
Use the following command syntax to create multiple address rewrite entries by using a CSV file:
Import-Csv <CSV file path> | ForEach { New-AddressRewriteEntry -Name $_.<Name CSV column heading> -InternalAddress $_.<InternalAddress CSV column heading> -ExternalAddress $_.<ExternalAddress CSV column heading> -OutboundOnly ([Bool]::Parse($_.<OutboundOnly CSV column heading>)) -ExceptionList ($_.<ExceptionList CSV column heading>.Split(","))}
To use a CSV file in the Exchange Management Shell to create multiple address rewrite entries
Create and populate a CSV file that is named
C:\ImportAddressRewriteEntries.csvRun the following command:
Import-Csv c:\ImportAddressRewriteEntries.csv | ForEach { New-AddressRewriteEntry -Name $_.Name -InternalAddress $_.InternalAddress -ExternalAddress $_.ExternalAddress -OutboundOnly ([Bool]::Parse($_.OutboundOnly)) -ExceptionList ($_.ExceptionList.Split(","))}
For detailed syntax and parameter information, see New-AddressRewriteEntry.