Copy-MapiItem

Description

Copies one or more items from one folder to another.

Syntax

Note: Parameters in orange are optional.

Copy-MapiItem
-SourceFolderMapiObject<Mapi.NET.Folder>
-DestinationFolderMapiObject<Mapi.NET.Folder>
-ItemIDMapi.NET.EntryID[]

Copy-MapiItem
-SourceFolderMapiObject<Mapi.NET.Folder>
-DestinationFolderMapiObject<Mapi.NET.Folder>
-MapiObjectMapiObject<Mapi.NET.EntryID>[]

Parameters

SourceFolderA Mapi.NET.Folder object that is the source folder containing the list of items to be copied.  Use Get-MapiFolder to get an instance of this object."
DestinationFolderA Mapi.NET.Folder object that is the destination folder to receive the copied items.  Use Get-MapiFolder to get an instance of this object"
ItemIDA list of one or more Mapi.NET.EntryID objects, each one representing an item in SourceFolder.  EntryID objects can be retrieved using Get-MapiContents.  Alternatively, objects returned by Get-MapiItem also hold an EntryID value at object.MapiObject.EntryID.  EntryID objects can also be created through auto-conversion from string representations (a hexadecimal string).
MapiObjectThis is an alternate representation of an EntryID object that is wrapped by the generate 'MapiObject<>' type.  This is the object type returned by Get-MapiContents

Remarks

This cmdlet copies one or more specific items from a source folder to a destination folder.

Note that if one of the items to be copied is moved or deleted before the copy operation is started on that item, the entire operation will fail - this is a limitation of MAPI and not the cmdlet.  This cmdlet is a wrapper around the mapi IMapiFolder::CopyMessages call.

If the list of items is of a high count (greater than 20), a progress bar will be shown in interactive PowerShell consoles.  Additionally, when copying items between messages stores, for example between a mailbox and a PST file or between a mailbox and Public Folders, a large list of items can take some time to complete.  The MAPI implementation is not threaded or speed optimized.

Additionally, it is unreasonable to attempt to copy 1000s of items using this method in a single call.  There are buffer limits that prevent sending or receiving overly large commands.  If there is need to copy large quantities of items, the list should be broken up in to smaller lists and enumerated through multiple calls to Copy-MapiItem.