Diese Seite ist noch nicht auf Deutsch verfügbar. Sie sehen bis dahin die englische Version.

The Outlook add-in

Signatures for Outlook for Android and iOS, advanced features for all platforms

Overview: What the add-in does Requirements: Technical prerequisites Configuration and deployment options

🔗Overview

With a Benefactor Circle license, you gain access to the Set-OutlookSignatures add-in.

The add-in makes signatures available in Outlook for iOS and Android, while supporting all Outlook editions across platforms. It's an ideal solution for Outlook editions that don't yet support roaming signatures and is particularly helpful in unmanaged BYOD scenarios.

It intelligently selects the appropriate signature based on the sender address, the type of item (new email, reply, or appointment), and any custom rules you define.

✨
Automatic Selection
Applies correct signatures on item creation.
👁️
Taskpane Preview
Users can manually select or preview signatures.
☁️
On-Prem Roaming
Cloud-like experience for on-premises mailboxes.
🛡️
Privacy First
No middleware or proxy servers. Local execution.
⚙️
Full Control
You control the version and configuration.
💎
Low Cost
Self-hosting keeps license costs minimal.
🚀
Enterprise Ready
Exchange Online and On-Premises support.

🔗Usage

From an end user perspective, basically nothing needs to be done: When writing a new email, answering an email, or creating a new appointment, the add-in automatically adds the corresponding default signature.

For advanced usage, a taskpane is available to manually choose signatures, preview items, or override settings for debug logging.

🌐

Web (Exchange Online), New Outlook for Windows/Mac

  • Emails: "Message" tab > "Apps" icon
  • Appointments: Ribbon > "…" menu
💻

Classic Outlook for Windows and Mac

  • Emails: "Message" tab > "All apps" icon
  • Appointments: "Meeting" tab > "All apps" icon
🏢

Outlook for the web (on-prem)

  • Compose: Lower right corner of the window
  • Appointments: Right side of the top menu bar
  • Read mode: Left of the reply button
📱

Mobile (iOS & Android)

  • Read mode: Three dots ("…" or "⋮") in the header
  • Compose: Signatures are added automatically
  • Note: Taskpanes are only supported in Read mode on mobile

🔗Requirements

🔗Outlook clients

The add-in works for all Microsoft-supported Outlook clients. It runs in the security context of the user and supports delegate scenarios.

Standard Mailboxes

The add-in accesses signature information that the Benefactor Circle add-on has written to the user's mailbox in client or SimulateAndDeploy mode.

Shared mailboxes added with the credential of the logged-on user are directly supported.

Shared Mailboxes

For shared mailboxes added with separate credentials, the add-in must be installed for that specific identity to access its signature data.

🔗Web server and domain

The requirements for your web server are straightforward:

  • Reachable from mobile devices via the public internet.
  • Use a dedicated host name (e.g., https://outlookaddin01.example.com). Do not use subdirectories.
  • A valid TLS certificate. Let's Encrypt is a good free alternative, especially when used with an ACME client for auto-renewal.
  • Production servers should not return Cache-Control headers like no-cache or no-store for images.

Static website hosting in Azure Storage is an uncomplicated, affordable and fast alternative. It includes a Microsoft-issued certificate, even in the free tier.

🔗Entra ID app

When mailboxes are hosted in Exchange Online, the add-in needs an Entra ID app to access the mailbox. Creating a separate app is strongly recommended.

powershell.exe -noexit -file "c:\test\sample code\Create-EntraApp.ps1" -AppType "OutlookAddIn" -AppName "Set-OutlookSignatures Outlook add-in" -OutlookAddInUrl "https://yourhost.yourdomain.com"

For manual configuration, the following Delegated Graph API permissions must be granted with admin consent:

Mail.Read

Allows reading emails in the current user's mailbox. Required due to Microsoft restrictions accessing roaming signatures.

GroupMember.Read.All

Allows the app to check group memberships to verify license groups for the signed-in user.

User.Read.All

Required to retrieve the User Principal Name (UPN) for a given SMTP email address.

Authentication: Use Single-page application with a redirect URI of brk-multihub://yourhost.yourdomain.com.

🔗Configuration and deployment

With every new release of Set-OutlookSignatures, the Benefactor Circle add-on comes with an updated Outlook add-in. You must update your deployment whenever the add-in version or your add-in configuration changes.

It is recommended to use at least two separate dedicated hostnames: One for testing and one for production (e.g., https://outlookaddin01test.example.com and https://outlookaddin01.example.com).

Deploying the add-in is a simple and fast three-step process: Configuring the code, uploading the files to a web server, and rolling out the manifest to your mailboxes.
You must update your deployment whenever the add-in version or your add-in configuration changes.

🔗Step 1: Configuration (Prepare)

The add-in is built using the run_before_deployment.ps1 script. This script injects your technical details into the source code and generates a publish folder containing your customized add-in code, include the manifest.xml file used for deployment.

General Settings

  • Versioning: Increment this every time you change a setting. This is the only way to force Outlook to clear its local cache and download the new files.
  • Deployment URL: Define your dedicated hosting domain (e.g., https://outlookaddin01.example.com).
  • Cloud Environment: Set your environment and Entra ID Client ID.
  • Debug Logging: Enable or disable detailed execution logs.

Automation Rules

  • Platform Targeting: Choose which hosts add signatures automatically.
  • Item Types: Enable automation for emails, appointments, or both.
  • Client Signatures: Optionally disable signatures configured by users.

Custom Rules Logic

Modify CustomRulesCode.js to influence signature selection at runtime based on:

  • Internal vs. external recipients
  • The sender's email address
  • Specific customers in the To field
  • Mail vs. Appointment types
  • Subject line keywords
  • Item status (New, Reply, or Forward)

You can even generate unique signatures at runtime without choosing a pre-deployed template. See .\sample code\CustomRulesCode.js for details.

🔗Step 2: Hosting (Publish)

Deployment: Run run_before_deployment.ps1 and upload the content of the publish folder to your web server.

  • The files must be hosted at the root of a dedicated host name (e.g., https://outlookaddin01.example.com). Subdirectories, such as https://www.example.com/outlookaddin01, are not supported.
  • Do not upload the publish folder itself, only its content, including subfolders.
  • Static website hosting in Azure Storage is an uncomplicated, affordable and fast alternative. It includes a Microsoft-issued certificate, even in the free tier.

🔗Step 3: Rollout (Deploy)

When the manifest.xml file, the configuration or another part of the Outlook add-in changes, you need to tell your mailboxes that an updated version or configuration is available and must be downloaded.

The information from the manifest file is stored in the assigned mailboxes, but not the add-in itself - every Outlook client downloads a local copy of the add-in based on the one-time information transfer from the manifest file.

These downloaded files are cached locally. The cache is only updated when a manifest file with a changed version number is added to the configuration of the mailbox, or when the cache gets cleared manually.

Individual Installation (Sideloading)

Ideal for test scenarios. Sideloading of add-ins may have been disabled by your administrators.

  • Exchange Online: Open https://outlook.cloud.microsoft/mail/inclientstore > My add-ins > Add from file.
  • On-prem: Open https://YourMailServer.example.com/owa/#path=/options/manageapps > Add from file.
  • Removal: Draft a new mail, click the Apps button, right-click the add-in and select Uninstall.

Enterprise Deployment (Production)

Ideal for mass deployment after the test phase.

Both methods share the same backend and are usually too slow for test scenarios: Microsoft documents state up to 24 hours for new add-in deployments, and up to 72 hours for changes to existing deployments. Consider clearing the Outlook add-in cache to speed up and test the deployment on select clients.

🔗Logging and troubleshooting

Troubleshooting Outlook add-ins can be complicated because the software operates through both a visible taskpane (triggered manually) and invisible background processes (launch events triggered by Outlook). While the interface may appear functional, background tasks — such as signature injection — can sometimes fail due to environment-specific settings or local caching issues. Use the following procedures to capture diagnostic logs for targeted analysis and to speed up testing of new releases and configuration settings.

Runtime logging

The add-in outputs diagnostic data to the browser console and the internal logging box within the taskpane. However, certain environments lack console access, and launch event (which run in the background) cannot send data to the taskpane UI. This makes it difficult to determine if a failure is due to a code error, a compilation issue, or if Outlook simply failed to trigger the event.

While you can enable the DEBUG parameter via run_before_deployment.ps1 to force event logging directly into the body of new emails, this is a heavy-handed approach. Most Outlook editions provide more elegant ways to capture runtime logs:

Outlook Web

Since the web version runs in a browser, standard web debugging tools are sufficient.

  1. Press F12 (or right-click and select "Inspect") to open the browser’s developer tools.
  2. Go to the Console tab to monitor all add-in activity.
Classic Outlook for Windows

You can redirect add-in activity to a local text file by modifying the Windows Registry.

  1. Define your log file path by setting the default value of the following key: HKCU\Software\Microsoft\Office\16.0\WEF\Developer\RuntimeLogging. You can execute this quickly via PowerShell:

    $Logfile = "c:\test\outlook_add-in_runtimelogging.txt"

if (-not (Test-Path "HKCU:\Software\Microsoft\Office\16.0\WEF\Developer\RuntimeLogging")) {
  New-Item -Path "HKCU:\Software\Microsoft\Office\16.0\WEF\Developer\RuntimeLogging" -Force
}

Set-ItemProperty -Path "HKCU:\Software\Microsoft\Office\16.0\WEF\Developer\RuntimeLogging" -Name "(Default)" -Value $Logfile

  2. Restart Outlook.

The specified file will now record all add-in activity, including launch event details and Set-OutlookSignatures specific messages.

New Outlook for Windows

New Outlook allows you to attach developer tools directly to the application process.

  1. Close New Outlook.
  2. Launch it from a command prompt or the Run dialog: 
    olk.exe --devtools

This opens a secondary window containing the Edge Developer Tools. Select the Console tab to view live logs from launch events and Outlook add-ins.

Classic and New Outlook for macOS

On macOS, you can enable runtime logging through the terminal.

  1. Force quit Outlook.
  2. Run the following command to set the log file destination: 
    defaults write com.microsoft.Outlook CEFRuntimeLoggingFile -string "outlook_add-in_runtimelogging.txt"
  3. Open Outlook.

Add-in activity is now logged to the file ~/library/Containers/com.microsoft.Outlook/Data/outlook_add-in_runtimelogging.txt, including all messages from launch events and Outlook add-ins.

Outlook for Android, Outlook for iOS

Mobile versions of Outlook do not support native runtime logging. To troubleshoot these platforms, you must use the "last resort" method: Enable the DEBUG parameter in your configuration via run_before_deployment.ps1 to see event logs within the email body.

Clear the Outlook add-in cache

When testing, Outlook sometimes takes too long updating its cache. Follow these official Microsoft instructions to manually clear it:

  • Outlook for Mac: Official instructions from Microsoft.
  • Outlook for iOS: Taskpane > Advanced options > Reload add-in.
  • Outlook for Android: App info > Force Stop > Clear Cache (do not tap Clear Data).

Restart Outlook after clearing the cache, even if not explicitly prompted. Allow up to 10 minutes for add-ins to fully reload, especially in Classic Outlook for Windows. If launch events fail to trigger, a second restart usually resolves the issue.

🔗Remarks

General Platform Notes

  • Roaming Signatures: Microsoft currently limits add-in access to roaming signatures. The add-in uses data from the last run of Set-OutlookSignatures (v4.14.0+) as a workaround until this is resolved.
  • Online Connection: Microsoft APIs only allow access to online content. The add-in requires an active connection to the mailbox and cannot access offline cache or the local file system.
  • Event Support: Automation relies on Outlook "Launch Events" (e.g., OnNewMessageCompose). Note that Microsoft does not currently support add-ins for calendar invite responses.
  • Office.js: Microsoft dynamically updates the underlying framework. If automation behaves unexpectedly, the taskpane remains the reliable manual fallback.

Outlook for iOS & Android

  • Only Exchange Online mailboxes are supported.
  • Taskpanes are not permitted by Microsoft during compose mode; signatures are applied automatically via events.
  • Automated signatures for new appointments are not yet supported by the mobile APIs.

Outlook for Mac

  • New Outlook for Mac: Fully supported and recommended.
  • Classic Outlook for Mac: Out of support by Microsoft. Support is provided on a best-effort basis due to API instability on this legacy platform.

Outlook for the web (On-Prem)

  • Launch events are not supported by the on-premises APIs; signature selection must be done via the taskpane.
  • Images may be replaced with alternate descriptions due to a known bug in the Microsoft office.js framework for on-prem hosts.

Classic Outlook for Windows

  • Launch events can be unstable for on-prem mailboxes; use the taskpane if signatures do not appear automatically.
  • Exchange Online mailboxes must use a version supporting Nested App Authentication, as legacy EWS tokens are deprecated.

The Benefactor Circle license funds the open-source mission, ensuring the core engine remains free and peer-reviewable for the global community.