Edit NK2 files from command-line.

NK2Edit allows you to write small and simple scripts that can add/modify/delete records in .NK2 files, and execute them from command-line, without displaying any user interface.

NK2Edit Script Features

  • NK2Edit scripts can be executed in the logon script of any computer (Starting from Windows 2000) without need of any installation.
  • NK2Edit scripts allow you to automatically remove specific types of NK2 records. For example, you can choose to remove all SMTP addresses, or you can choose to remove all SMTP addresses with specific domain.
  • NK2Edit scripts allow you to automatically fix common errors and problems that occurred in the NK2 files of all users in your organization. For example, if there was a change in any email address or in the MS-Exchange addresses, and the addresses stored in the NK2 are now invalid, simply create a script that modifies the old addresses to the new addresses, and the problem will be solved for all users at once.
  • NK2Edit scripts can also fix corrupted NK2 files: When NK2Edit script modifies the NK2 file, it also rebuilds the entire file and removes errors found in it, so if there is any problem in the NK2 file and Outlook cannot load it, there is a good chance that the problem will be solved after running the NK2 script.

Getting Started

A script can be executed from command-line by using /script parameter:
NK2Edit.exe /script <Script Filename> <NK2 Source> <NK2 Destination>

The <Script Filename> parameter specifies the filename contains the script commands. The <NK2 Source> is the NK2 filename to load, and the <NK2 Destination> is the NK2 file to save your changes. If <NK2 Destination> is not specified or you specify an empty string (""), your changes will overwrite the filename specified in <NK2 Source> parameter.
You can use /LogFile parameter in order diagnose problems with your script. When you use the /LogFile parameter, all actions made by the script are saved into the specified text file.

For NK2Edit with commercial license: You can also specify $default instead of the NK2 filename. When $default is specified, NK2Edit uses the NK2 file of the default Outlook profile, in the context of the user that executes the script.

Examples:
NK2Edit.exe /script "f:\scripts\myscript.txt" "C:\Documents and Settings\Administrator\Application Data\Microsoft\Outlook\Outlook.NK2"
NK2Edit.exe /script "f:\scripts\myscript.txt" "C:\Documents and Settings\Administrator\Application Data\Microsoft\Outlook\Outlook.NK2" "c:\temp\mynewfile.nk2"
NK2Edit.exe /script "f:\scripts\myscript.txt" $default
NK2Edit.exe /script "f:\scripts\myscript.txt" $default "" /LogFile "f:\%computername%.txt"
NK2Edit.exe /script "f:\scripts\myscript.txt" "C:\Documents and Settings\Administrator\Application Data\Microsoft\Outlook\Outlook.NK2" "" /NoBackup /LogFile "f:\mylog.txt"

Starting from version 2.65, you can also use /script_express command-line option, which allows you to run a script without using external script file:
NK2Edit.exe /script_express <NK2 File> 'Script Line 1' 'Script Line 2' 'Script Line 3' ...

When using /script_express, every script line must be delimited with single-quote characters and you should not add any other command-line options after the script lines. All other command-line options must precede the /script_express command-line option.

Examples:
NK2Edit.exe /LogFile "express_log.txt" /script_express $default 'If AddressType equal "EX" EXToSMTP' 'If Domain Equal "gmail.com" Delete'
NK2Edit.exe /LogFile "express_log.txt" /AutoExportToMessageStore 1 /script_express $default 'If AddressType equal "EX" EXToSMTP'
NK2Edit.exe /script_express "mynk2.nk2" 'If Domain Equal "gmail.com" Delete' 'If Domain Equal "yahoo.com" Delete' 'If Domain Equal "hotmail.com" Delete'

Currently, the scripts of NK2Edit support the following commands:

  • If - Allows you to remove and modify existing records according to the specified condition.
  • Add - Allows you add new records, by specifying address type, name, and email/Exchange string.
  • MergeMode - Specifies the merge mode for Add command.
  • RemoveQuotes - Removes the single-quotes from the display names and drop-down names in all NK2 records.
  • RemoveDoubleQuotes - Removes double-quotes from the display names and drop-down names in all NK2 records.
  • TrimSpaces - Trims leading/trailing whitespaces from the email addresses and display names in all NK2 records.

It's possible that more commands will be added in the future according to customer's requests.

Automatic Backups

When editing NK2 file using a script, NK2Edit automatically creates 2 types of backups:
  • First Time Backup: This backup is created only in the first time that NK2Edit overwrite existing NK2 file. The backup file is saved with .NK2Edit.First.bak extension. If you don't want that this backup will be created, use /nofirstbackup command-line option.
  • Every Save Backup: This backup is created on every time that changes are made into existing NK2 file. The backup file is saved with .NK2Edit.Cmd.bak extension. If you don't want that this backup will be created, use /nobackup command-line option.

It's highly recommended to allow NK2Edit to backup the NK2 files, unless you maintain your own backup system. Making backups for NK2 files insure that if something goes wrong with your scripts, you'll be able to restore the original NK2 file.

General guidelines for NK2Edit scripts

  • The script commands are not case sensitive.
  • You can edit the script with notepad or any other text editor and then save it to Ascii or Unicode text file. If you have non-English characters in your script, it's recommended to save the file as Unicode.
  • You must write every command in separated line.

Using the 'If' command

The general syntax of 'If' command is:
If [FieldName] [Operator] [Value] [Action]

The [FieldName] may specify the following fields: AddressType, DisplayName, Email, DropDown, SearchString, Domain, DisplayType, Weight, SMTPEmail (SMTP email For Exchange records only), and EmailString. For DisplayType field, you can specify one of the following numeric values: 0 for Mail User, 1 for Distribution List, 5 for Private Distribution List, and 6 for Remote User.
The EmailString field (Added in version 2.95) is a combination of Email and SMTPEmail fields, which means that it returns the correct email address string for both SMTP and Exchange records.

The [Operator] may specify the following values: Contain, Equal, BeginWith, EndWith, NotContain, NotEqual, NotBeginWith, NotEndWith, Like, LengthRange, IsNumber. For Weight and DisplayType fields, the following operators also available: GreaterThan, LessThan.

The [Action] may contain one of the following actions to perform on the records:

  • Delete - Delete the record
  • NoDelete - Mark the record for 'no delete', so the record won't be deleted even if other 'if' command request to delete it.
  • Set [FieldName] [Value] - Set a value into the specified string. [FieldName] may also contain 'weight' string, if you want to set the weight of the NK2 record. [FieldName] may also contain 'SendingFormat' string, if you want to set the sending format. For 'SendingFormat' field, you can use the following values:
    • 0 - Send using Outlook Rich Text Format
    • 1 - Let Outlook decide the best sending format
    • 7 - Send Plain Text Only
  • Replace [Find String] [Replace String] - Replace a string with a new string in all major fields.
  • ReplaceField [FieldName] [Find String] [Replace String] - Replace a string with a new string only in the specified field.
  • ReplaceCS [Find String] [Replace String] - The same as Replace action, but the find string is case sensitive.
  • ReplaceFieldCS [FieldName] [Find String] [Replace String] - The same as ReplaceField action, but the find string is case sensitive.
  • AutoFill - Automatically fill the DropDown Name and Search String of the record with the right values. It's recommended to use this action after Set or ReplaceField actions.
  • EXToSMTP - Automatically convert EX record into SMTP record. This action only works if the NK2 record stores the correct SMTP address of the EX record. (You can look at the 'SMTP Address' column of the EX record. If it's empty, it means that you cannot use the EXToSMTP action)
  • RemoveLinkToProfile - This action removes the link to profile of SMTP addresses. This action is only relevant for SMTP records with 'Yes' value on the 'Linked To Profile' column.
Here's some examples for using If command:
  • Put all emails with @mydomain.com domain at the top of the AutoComplete list, by giving them very high weight value:
    if EmailString Contain "@mydomain.com" set weight 1000000
  • Delete all non-private distribution lists:
    if DisplayType Equal 1 delete
  • Delete all SMTP addresses:
    If AddressType equal "SMTP" Delete
  • Delete all Exchange addresses:
    If AddressType equal "EX" Delete
  • Delete all records that their display name contains 0 - 7 characters:
    If DisplayName LengthRange 0-7 Delete
  • Delete all SMTP addresses except of email addresses of hotmail.com and msn.com: (The NoDelete command overrides the delete command)
    If AddressType equal "SMTP" Delete
    If Email Contain "@hotmail.com" NoDelete
    If Email Contain "@msn.com" NoDelete
  • Delete all records that their domain name is gmail.com :
    If Domain Equal "gmail.com" Delete
  • Delete all records that their email address ends with .co.uk
    If EmailString EndWith ".co.uk" Delete
  • Delete all records begins with 'support' and ends with .net
    if EmailString Like "support*@*.net" delete
  • Switch from specific MS-Exchange email to SMTP email address:
    if Email Equal "/o=First Organization/ou=first administrative group/cn=Recipients/cn=Nirs" Set Email "smtp_email@nirsoft.net" Set AddressType "SMTP" AutoFill
  • Switch all MS-Exchange addresses to SMTP email addresses automatically:
    If AddressType equal "EX" EXToSMTP
  • Set the sending format of all SMTP addresses to automatic (Let Outlook decide the best sending format)
    If AddressType equal "SMTP" Set SendingFormat 1
  • Find the record with aaaaa@msn.com as email address, and change it to helloworld@msn.com as email and 'Hello World' as display name. Also, fill the appropriate values in the DropDown and Search string (AutoFill) .
    If Email Equal "aaaaa@msn.com" Set Email "helloworld@msn.com" Set DisplayName "Hello World" AutoFill
  • Find the record with support@nirsoft.net as email address and delete it:
    If EmailString Equal "support@nirsoft.net" Delete
  • Find all Exchange records (AddressType="EX") and change their address to a new server:
    If AddressType equal "EX" ReplaceField "Email" "/o=First Organization/ou=first administrative group" "/O=NirSoft Organization/OU=NirSoft"
  • Find all SMTP email addresses with @domain1.com and change their domain to @domain2.com
    Also, update the DropDown and Search strings according to the email address change (AutoFill).
    If AddressType equal "SMTP" ReplaceField "Email" "@domain1.com" "@domain2.com" AutoFill
  • Replace 'NirSoft' string to 'SoftNir' in all SMTP records. This change will affect all major fields, including the display name and the email address.
    If AddressType equal "SMTP" Replace "NirSoft" "SoftNir"
  • Delete all records that their search string is a number:
    If SearchString IsNumber Delete

Using the 'Add' command

The general syntax of 'Add' command is:
Add [Address Type] [Email/Exchange String] [Display Name] {Display Type}

The {Display Type} is optional parameter that may contain the following values: 0 for standard mail user (default), 1 for distribution list, and 6 for remote user

Examples for using Add command:

  • Add "SMTP" "nirsofer@yahoo.com" "Nir Sofer"
  • Add "EX" "/o=First Organization/ou=first administrative group/cn=Recipients/cn=Nirs" "Nir Sofer"
  • Add "EX" "/o=First Organization/ou=first administrative group/cn=Recipients/cn=everyone" "Everyone" 1

If the Email address or Exchange account already exist, the MergeMode is used to determine whether to add the record, replace it with the old one, or discard it.

Using the 'MergeMode' command

The general syntax of 'MergeMode' command is:
MergeMode [Mode Number]

Examples for using MergeMode command:

  • Specifies that the Add command should always add the record, even if it already exist (duplicates might be created):
    MergeMode 1
  • Specifies that if the email already exists, the Add command should replace it with the new one:
    MergeMode 2
  • Specifies that if the email already exists, the Add command should not add the record:
    MergeMode 3

Script example with all commands

if AddressType Equal "SMTP" Delete
if Email Contain "@hotmail.com" NoDelete
if Email Contain "@msn.com" NoDelete
if Email Equal "abcdefg@msn.com" Set Email "helloworld@msn.com" Set DisplayName "Hello World"
MergeMode 2
Add "SMTP" "nirsofer@yahoo.com" "Nir Sofer"
Add "SMTP" "abcdefg@hotmail.com" "abcdefg"
Add "EX" "/o=First Organization/ou=first administrative group/cn=Recipients/cn=Nirs" "Nir Sofer"
Add "EX" "/o=First Organization/ou=first administrative group/cn=Recipients/cn=everyone" "Everyone" 1
If AddressType equal "EX" ReplaceField "Email" "/o=First Organization/ou=first administrative group" "/O=NirSoft Organization/OU=NirSoft"
If AddressType equal "SMTP" ReplaceField "Email" "@domain1.com" "@domain2.com" AutoFill
If AddressType equal "SMTP" Replace "NirSoft" "SoftNir"
RemoveQuotes

Script With Parameters

Starting from version 1.85, you can also create a script with parameters that are loaded from comma-delimited (csv) or tab-delimited text file.
In the script file, a parameter is specified as *X. *0 for the first parameter, *1 for the second parameter, *2 for the third parameter, and so on (up to 10 parameters).
The parameters file (input file) is specified with the /ScriptInput command-line option.

For example, you can create a script with the following script line:
if Email Equal "/o=Domain/ou=First Administrative Group/cn=Recipients/cn=*0" set Email "/o=Domain/ou=First Administrative Group/cn=Recipients/cn=*1" AutoFill

In the input file, you specify the 2 parameters for every line, delimited by comma (You can also use tab-delimited file, NK2Edit automatically detects the file type):
user01, newuser01
user02, newuser02
user03, newuser03
user04, newuser04

In order the execute the script with the input file, use both /ScriptInput and /script command-line option:
NK2Edit.exe /ScriptInput "inputfile.txt" /script "f:\scripts\myscript.txt" $default ""

In the above example, NK2Edit will execute the specified script line 4 times, each time with different parameters values taken from the input file. So it's exactly like executing the following 4 script lines:
if Email Equal "/o=Domain/ou=First Administrative Group/cn=Recipients/cn=user01" set Email "/o=Domain/ou=First Administrative Group/cn=Recipients/cn=newuser01" AutoFill
if Email Equal "/o=Domain/ou=First Administrative Group/cn=Recipients/cn=user02" set Email "/o=Domain/ou=First Administrative Group/cn=Recipients/cn=newuser02" AutoFill
if Email Equal "/o=Domain/ou=First Administrative Group/cn=Recipients/cn=user03" set Email "/o=Domain/ou=First Administrative Group/cn=Recipients/cn=newuser03" AutoFill
if Email Equal "/o=Domain/ou=First Administrative Group/cn=Recipients/cn=user04" set Email "/o=Domain/ou=First Administrative Group/cn=Recipients/cn=newuser04" AutoFill

When executing the script, the nk2 record with /o=Domain/ou=First Administrative Group/cn=Recipients/cn=user01 will be replaced with /o=Domain/ou=First Administrative Group/cn=Recipients/cn=newuser01 , nk2 record with /o=Domain/ou=First Administrative Group/cn=Recipients/cn=user02 will be replaced with /o=Domain/ou=First Administrative Group/cn=Recipients/cn=newuser02, and so on...

Return to NK2Edit introduction page