📋 Outlook Add-In (new): Central configuration via PowerShell

This guide describes the automated setup of the Outlook Add-In for administrators using a PowerShell script for the central configuration of server settings for users and groups.

Step 1 – Download and extract the files

In the first step, download the required setup package via the following link:

Click here: Download setup script for the Outlook Add-In

Save the downloaded ZIP file to your computer, for example in your Downloads folder. Then extract the ZIP file completely (right-click the file and select "Extract All").

Now open the folder you just extracted. Inside, you will see a folder named setup. Open this setup folder.

Under a path such as C:\Users\YourUsername\Downloads\setup\setup, exactly these three files must be present:

1. config.json (the configuration file you need to customize)

2. README.md (an English text guide)

3. setup.ps1 (the actual script that will be executed later)

Step 2 – Check prerequisites

Ensure that your system has Windows with PowerShell 5.1 or PowerShell 7+ installed. Internet access is mandatory to automatically install the required Microsoft.Graph module.

You also need a Microsoft 365 administrator account with the Global Administrator or User Administrator role. If you want to distribute the Outlook Add-In to entire groups, the Groups Administrator role is additionally required.

Step 3 – Customize the configuration file

Open the config.json file from your setup folder with a simple text editor (for example, the pre-installed Windows Notepad) and adjust the values to your environment.

Assigning the server URL

Enter the URL of your FTAPI server under ftapiUrl, for example https://your-server.ftapi.com.

"ExtensionSettings": {    "ftapiUrl": "https://your-server.ftapi.com"}

Defining users and groups

You can configure the Add-In either for individual users, for entire groups, or for both simultaneously:

Enter the Object IDs of individual users in the UserList – or leave the field empty if you only use groups.
Enter the Object IDs of Microsoft 365 groups whose members should be configured in the GroupList – or leave the field empty if you only use individual users.

Important: Use only the Object ID (a long combination of numbers and letters), not the display name or the email address. You can find these IDs in the Microsoft Entra Admin Center under Identity → Users or Identity → Groups.

Step 4 – Executing the setup in PowerShell

Open a PowerShell console exactly in the directory where your extracted files are located. Navigate in PowerShell to the path that contains the setup.ps1 file (for example C:\Users\YourUsername\Downloads\setup\setup).

Execute the script with the following command:

.\setup.ps1

If a red error message regarding the execution policy appears, run this command beforehand and confirm with Enter:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

During the very first execution, the Microsoft.Graph module will be installed automatically, which may take a few minutes. Be sure to confirm the security prompt for the PSGallery (PowerShell Gallery) by pressing Y.

Step 5 – Verifying the results

Check the text output in PowerShell at the end. If the setup is successful, you will see messages like Successfully created extension or Successfully updated existing extension next to the user IDs.

For further verification, you can check the configuration directly via the Microsoft Graph Explorer:

Open https://developer.microsoft.com/en-us/graph/graph-explorer and sign in with your administrator account.
Execute the following query (replace <userId> with the user's Object ID):

GET https://graph.microsoft.com/v1.0/users/<userId>/extensions/com.ftapi.settings

The response should contain the "ftapiUrl" entry with your configured server URL.

Running the script again

The script can be executed again at any time – for example, to add new users or groups or to update the ftapiUrl after a server migration. Existing configurations will be updated, and no duplicates will be created.

Troubleshooting

Module installation fails

Check your internet connection. You can manually mark the PSGallery as trusted by running this command:

Set-PSRepository -Name PSGallery -InstallationPolicy Trusted

Authentication fails or access is denied

Ensure that the account used has the required roles. Also, check if Conditional Access Policies restrict login from your device or location, or if your tenant restricts app consent or access to the Graph API.

Group members are not found

Check if the Group Object ID is correctly stored in the config.json file and that you have not accidentally inserted spaces when copying. Ensure that your admin account has the Group.Read.All permission and that the group has not been deleted.

"Failed to process user"

Check if the User Object ID in the config.json is correct. The specific error message in the PowerShell output provides further information about the cause.

The Add-In does not adopt the server URL

First, ensure that the extension was written successfully (see Step 5). Ask the affected user to restart Outlook. Also, ensure that the URL entered under ftapiUrl is reachable from the user's network.

📋 Outlook Add-In: Rollout via the Microsoft 365 Admin Center