Note: PowerShell integration requires a ShareGate Migrate Pro or Enterprise subscription. It is not available on the Essentials plan.
Command
New-MailboxCopyOptions
Description
This command creates copy options for use in a mailbox copy operation.
To learn more about your mailbox copy options, see Copy mailboxes - Copy options.
Examples
Copy only emails from the past 90 days
$src = Connect-MicrosoftOnline
$dst = Connect-MicrosoftOnline
$copyOptions = New-MailboxCopyOptions -IncludeEmails -EmailCopyRangeStart (Get-Date).AddDays(-90)
$mailboxesToCopy = Get-Mailbox -Connection $src -Id 272980f8-cba2-4b7f-b020-12ea922d92c5
$mappings = Import-MailboxMappings -SourceConnection $src -DestinationConnection $dst -Path "C:\mappings\SharegateMailboxesMapping.csv"
Copy-Mailbox -SourceConnection $src -DestinationConnection $dst -CopyOptions $copyOptions -MappingSettings $mappings -Mailboxes $mailboxesToCopy
Copy using maximum mailbox concurrency
$src = Connect-MicrosoftOnline
$dst = Connect-MicrosoftOnline
$copyOptions = New-MailboxCopyOptions -IncludeEmails -MaxConcurrentMailboxes 128
$mailboxesToCopy = Get-Mailbox -Connection $src
$mappings = Import-MailboxMappings -SourceConnection $src -DestinationConnection $dst -Path "C:\mappings\SharegateMailboxesMapping.csv"
Copy-Mailbox -SourceConnection $src -DestinationConnection $dst -CopyOptions $copyOptions -MappingSettings $mappings -Mailboxes $mailboxesToCopy
Copy emails from the beginning of time to today
$src = Connect-Google
$dst = Connect-MicrosoftOnline
$copyOptions = New-MailboxCopyOptions -IncludeEmails
$mailboxToCopy = Get-Mailbox -Connection $src -Id 123456789012345678901
$mappings = Import-MailboxMappings -SourceConnection $src -DestinationConnection $dst -Path "C:\mappings\SharegateMailboxesMapping.csv"
Copy-Mailbox -SourceConnection $src -DestinationConnection $dst -CopyOptions $copyOptions -MappingSettings $mappings -Mailboxes $mailboxToCopy
Copy emails from a date range and include calendar events with new links
$startDate = [DateTime]::ParseExact("06-01-2024", "MM-dd-yyyy", $null)
$endDate = [DateTime]::ParseExact("12-01-2024", "MM-dd-yyyy", $null)
New-MailboxCopyOptions -IncludeEmails -EmailCopyRangeStart $startDate -EmailCopyRangeEnd $endDate -IncludeCalendar -CreateNewMeetingLinks
Copy emails from the beginning of time to today and include mailbox rules
New-MailboxCopyOptions -IncludeEmails -IncludeMailboxRules
Copy only contacts
New-MailboxCopyOptions -IncludeContacts
Copy only calendars with all events
New-MailboxCopyOptions -IncludeCalendar -CopyPastEvents
Copy only calendars with events from a specified past date
New-MailboxCopyOptions -IncludeCalendar -CopyPastEvents -CalendarCopyStartDate "2025-02-10"
Copy calendar events from today with new meeting links, mailbox rules, contacts, and emails from the past 180 days
$startDate = (Get-Date).AddDays(-180)
New-MailboxCopyOptions -IncludeEmails -EmailCopyRangeStart $startDate -IncludeCalendar -CreateNewMeetingLinks -IncludeContacts -IncludeMailboxRules
Copy all calendar events with new meeting links, mailbox rules, contacts, and emails from the past 180 days
$startDate = (Get-Date).AddDays(-180)
New-MailboxCopyOptions -IncludeEmails -EmailCopyRangeStart $startDate -IncludeCalendar -CreateNewMeetingLinks -CopyPastEvents -IncludeContacts -IncludeMailboxRules
Copy calendar events from a specified past date with new meeting links, mailbox rules, contacts, and emails from the past 180 days
$startDate = (Get-Date).AddDays(-180)
New-MailboxCopyOptions -IncludeEmails -EmailCopyRangeStart $startDate -IncludeCalendar -CreateNewMeetingLinks -CopyPastEvents -CalendarCopyStartDate "2025-01-01" -IncludeContacts -IncludeMailboxRules
Copy emails from the beginning of time to today, including deleted and junk
New-MailboxCopyOptions -IncludeEmails -IncludeMailboxRules -IncludeDeletedEmails -IncludeJunkEmails
Copy litigation hold and replace existing destination holds
New-MailboxCopyOptions -IncludeLitigationHold -ReplaceDestinationHolds
Syntax
New-MailboxCopyOptions
[-IncludeEmails <SwitchParameter>]
[-EmailCopyRangeStart <DateTime>]
[-EmailCopyRangeEnd <DateTime>]
[-IncludeCalendar <SwitchParameter>]
[-CreateNewMeetingLinks <SwitchParameter>]
[-CopyPastEvents <SwitchParameter>]
[-CalendarCopyStartDate <DateTime>]
[-IncludeContacts <SwitchParameter>]
[-IncludeMailboxRules <SwitchParameter>]
[-IncludeArchiveMailbox <SwitchParameter>]
[-IncludeDeletedEmails <SwitchParameter>]
[-IncludeJunkEmails <SwitchParameter>]
[-IncludeLitigationHold <SwitchParameter>]
[-ReplaceDestinationHolds <SwitchParameter>]
[-MaxConcurrentMailboxes <Int32>]
[-CopyToFolder <SwitchParameter>]
[-CopyIntoFolderName <String>]
Parameters
-CalendarCopyStartDate <DateTime>
Specifies the starting date from which the calendar events will be migrated.
Required? | False |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-CopyIntoFolderName <String>
Specifies the name of the destination subfolder when -CopyToFolder is set.
Required? | False |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-CopyPastEvents <SwitchParameter>
Specifies to copy past calendar events.
Required? | False |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-CopyToFolder <SwitchParameter>
Specifies to copy the mailbox content into a destination subfolder instead of the inbox root.
Required? | False |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-CreateNewMeetingLinks <SwitchParameter>
Specifies to replace the Team links in the calendar events.
Required? | False |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-EmailCopyRangeEnd <DateTime>
Specifies the ending date from which the emails will be migrated.
Required? | False |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-EmailCopyRangeStart <DateTime>
Specifies the starting date from which the emails will be migrated.
Required? | False |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-IncludeArchiveMailbox <SwitchParameter>
Specifies to copy the in-place archive mailbox.
Required? | False |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-IncludeCalendar <SwitchParameter>
Specifies to copy the mailbox calendar.
Required? | False |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-IncludeContacts <SwitchParameter>
Specifies to copy the mailbox contacts.
Required? | False |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-IncludeDeletedEmails <SwitchParameter>
Specifies to include the deleted emails.
Required? | False |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-IncludeEmails <SwitchParameter>
Specifies to migrate the mailbox emails.
Required? | False |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-IncludeJunkEmails <SwitchParameter>
Specifies to include the junk emails.
Required? | False |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-IncludeLitigationHold <SwitchParameter>
Specifies to copy the source mailbox litigation hold to the destination.
Required? | False |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-IncludeMailboxRules <SwitchParameter>
Specifies to copy the mailbox rules.
Required? | False |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-MaxConcurrentMailboxes <Int32>
Specifies the maximum number of mailboxes copied in parallel, up to 128. If not specified, ShareGate Migrate copies 16 mailboxes in parallel. Higher values are faster but use more CPU, memory, and network on the computer running the migration.
Required? | False |
Default value | 16 |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-ReplaceDestinationHolds <SwitchParameter>
Specifies to overwrite any existing holds on the destination mailbox with the source ones.
Required? | False |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |