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

Step 1 – Download and extract the files

First, download the required setup package via the following link:

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

Save the downloaded ZIP file on 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 it 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 now be present:

• config.json (the configuration file you need to adjust)

• README.md (an English text guide)

• setup.ps1 (the actual script that is run later)

Step 2 – Check the prerequisites

Make sure your system runs Windows with PowerShell 5.1 or PowerShell 7+. Internet access is mandatory in order to automatically install the required Microsoft.Graph module.

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

Step 3 – Adjust the configuration file

Open the config.json file from your setup folder with a simple text editor (for example the preinstalled Windows Editor/Notepad) and adjust the values to match your environment.

Assigning the server URL

Under ftapiUrl, enter the URL of your FTAPI server, 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 at the same time:

• Enter the Object IDs of individual users in the UserList – or leave the field out if you use groups exclusively.

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

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 – Running the setup in PowerShell

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

Run the script with exactly the following command:

.\setup.ps1

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

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

On the very first run, the Microsoft.Graph module is installed automatically, which can take a few minutes. Be sure to confirm the security prompt for the PSGallery (PowerShell Gallery) with the Y key.

Important: Files downloaded from the internet are blocked by Windows (Mark of the Web / Zone.Identifier). The Set-ExecutionPolicy command alone does not lift this block. For unsigned scripts from the internet, RemoteSigned still requires the block to be removed first. If setup.ps1 will not start despite the execution policy being set, remove the block using one of the following methods.

Remove the block on the ZIP file before extracting (recommended)

Right-click the downloaded ZIP file and select Properties. At the bottom, enable the Unblock option and confirm with OK. Only extract the file after that. This way all contained files are extracted without a block.

Unblock already extracted files via PowerShell

If the files are already extracted, you can remove the block via PowerShell. Run the following command in the setup folder to unblock all contained files:

Get-ChildItem -Path . -Recurse | Unblock-File

For a single file, this is sufficient:

Unblock-File -Path .\setup.ps1

Transfer the script content manually (last resort)

If the previous methods are not possible, open the setup.ps1 file in a text editor, copy the entire content and paste it into a locally created setup.ps1 file. Locally created files are not subject to the block and can be run directly.

Step 5 – Verifying the results

At the end, check the text output in PowerShell. On a successful setup you will see messages such as Successfully created extension or Successfully updated existing extension next to the users' 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.

• Run 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 entry "ftapiUrl" with your configured server URL.

One-time sign-in in the Add-In

After the central configuration has succeeded, a one-time sign-in is still required. Affected users must sign in once in the Outlook Add-In so that it becomes active. Without this one-time sign-in, the Add-In remains inactive despite a correctly written configuration.

Running the script again

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

Troubleshooting

The script will not run / is blocked

Files downloaded from the internet are blocked by Windows (Mark of the Web). The Set-ExecutionPolicy command alone does not lift this block. Remove the block as described in Step 4: either by right-clicking the ZIP file via Properties > Unblock before extracting, or via Unblock-File in PowerShell. As a last resort, the script content can be transferred into a locally created setup.ps1.

The 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

Make sure the account you use has the required roles. Also check whether Conditional Access Policies restrict sign-in from your device or location, or whether your tenant restricts app consent or access to the Graph API.

Group members are not found

Check whether the Group Object ID is entered correctly in the config.json file and that you did not accidentally add any spaces while copying. Make sure your admin account has the Group.Read.All permission and that the group has not been deleted.

"Failed to process user"

Check whether the User Object ID in the config.json is correct. The exact error message in the PowerShell output provides further insight into the cause.

The Add-In does not apply the server URL

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

Similar articles

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