Microsoft 365 Initialize IMAP script

Use m365_initialize_imap.ps1 when Transend Migration Console will access Microsoft 365 mailboxes through IMAP with application authentication. The script registers the Transend enterprise application as an Exchange Online service principal, enables IMAP where necessary, and grants that service principal full access to each mailbox in scope. By default it evaluates all users with mailboxes; use -Csv to limit the users in the migration.

The script records every service-principal, protocol, and mailbox-permission change in m365_restore_imap.json in your Documents directory. Keep this file if you may need to undo the changes. After the migration, run m365_restore_imap.ps1 from the same user account to restore the recorded mailbox settings and remove only the access added by the initialize script.

Setup

Download TMCTools.
From the TMCTools zip file, extract common.psm1, m365.psm1 and m365_initialize_imap.ps1 from the TMCTools/bin folder.
Ensure you have created the required app using m365_initialize_app.ps1.

Usage

.\m365_initialize_imap.ps1
  -AppId <AppId>
  -AppSecret <AppSecret>
  -TenantId <TenantId>
  -TransendAppId <TransendAppId>
  -TransendObjectId <TransendObjectId>
  [-Csv <Csv>]
  [-CloudEnvironment <Default | DoD | GCCHigh | China | Germany>]

Parameters

Parameter	Required	Values	Description
`-AppId`	Yes	App ID	The application ID to use for authentication.
`-AppSecret`	Yes	App secret	The application secret to use for authentication.
`-TenantId`	Yes	Tenant identifier	The tenant ID to connect to.
`-TransendAppId`	Yes	TMC app ID	The Enterprise app Application ID for TMC.
`-TransendObjectId`	Yes	TMC object ID	The Enterprise app Object ID for TMC.
`-Csv`	No	Path to a CSV file	A CSV file containing a list of objects to process.
`-CloudEnvironment`	No	`Default`, `DoD`, `GCCHigh`, `China`, `Germany`	The cloud environment to connect to. Use this option if your tenant is not in the worldwide cloud.

Examples

Example 1: Configure all users for IMAP migration

Note that TransendAppId and TransendObjectId are the application and object IDs associated with the Entra Enterprise application for TMC, not the application registration for TMC. You’ll find the required IDs under Enterprise apps instead of App registrations.

.\m365_initialize_imap.ps1 -AppId '8b26caf2-2ef6-4a9d-9c27-98616d1c1294' -AppSecret '9pitRZoTezs6M0b~bgcibEfkG6qMaczuNV25Ol6m' -TenantId 'example.org' -TransendAppId 'ee86460f-1b32-4fe8-8b2d-9e215e73ac98' -TransendObjectId 'dac44598-2f1a-46ba-9597-c33fe94a8cd9'

Example 2: Configure select users for IMAP migration

To limit the users for which IMAP will be configured, you’ll need to create a CSV with a single field named Identity that includes any of the following attributes:

ID
UPN
Email address
Display name

For example:

Identity
user1@example.org
user2@example.org
user3@example.org

.\m365_initialize_imap.ps1 -AppId '8b26caf2-2ef6-4a9d-9c27-98616d1c1294' -AppSecret '9pitRZoTezs6M0b~bgcibEfkG6qMaczuNV25Ol6m' -TenantId 'example.org' -TransendAppId 'ee86460f-1b32-4fe8-8b2d-9e215e73ac98' -TransendObjectId 'dac44598-2f1a-46ba-9597-c33fe94a8cd9' -Csv 'C:\Temp\users.csv'

Troubleshooting

Review the log file in your Documents directory for more information.