#Delivery to Outlook

A published signature reaches users through up to three channels. Most organizations use the add-in for everyone and add the Windows agent for classic Outlook in the domain.

Outlook for iOS/Android and the built-in mail apps do not run add-ins; the transport rule covers those messages.

#Outlook add-in

#What it does

• Automatically. When a user starts a new message, a reply or a forward, Outlook runs the add-in, which requests the signature from the server and inserts it (new message → full signature; reply/forward → short signature).
• Manually. The Signature button on the ribbon opens a pane with a preview and an Insert signature button. It works everywhere, even where automatic insertion is not available.
• Offline. The last signature is cached in the user's roaming settings and inserted if the server cannot be reached.
• No duplicates. The add-in marks messages with an X-SignetMail header and turns off the user's own Outlook signature, so there are never two.

Sign-in uses Nested App Auth: the add-in reuses the account the user is already signed in with, silently and without a pop-up. Classic Outlook for Windows does not support this; use the agent there.

#Prerequisites

In the Entra app registration the redirect URI brk-multihub://<host> must exist (see Entra setup).

#Deploy to the tenant

1. Open Microsoft 365 admin center → Settings → Integrated apps → Upload custom apps.
2. App type Office Add-in, choose Provide link to manifest file and enter https://<host>/addin/manifest.xml.
3. Assign it to the users. Start with a pilot group, then everyone.
4. Wait. It can take up to a few hours (sometimes up to 24) until the add-in appears in Outlook.

The manifest is generated by the server from its own settings, so it always carries the right addresses.

For a quick test on one mailbox: in Outlook on the web choose Get Add-ins → My add-ins → Custom add-ins → Add from URL and paste the manifest address.

#Testing

1. Open a new message — the signature should appear within a moment.
2. Click Signature on the ribbon to see the pane with preview and hash.
3. Compare with Who gets which signature in the portal.

#Limitations

• Automatic insertion depends on the client and account type; the ribbon button always works.
• Gmail accounts connected to new Outlook do not run add-ins.
• The user cannot hand-edit the inserted signature in the signature settings; that is intentional.

#Windows agent

#What it does

For classic Outlook (the desktop application) on domain-joined PCs, the agent keeps the local signature files current. At every start it:

1. Requests new and reply signatures from the server as the signed-in user (Kerberos; no passwords).
2. If the hash changed or files are missing, writes into %APPDATA%\Microsoft\Signatures: SignetMail.htm, SignetMail.txt, SignetMail.rtf and the same for SignetMail Reply.
3. Sets NewSignature and ReplySignature in HKCU\Software\Microsoft\Office\16.0\Common\MailSettings.
4. Sets DisableRoamingSignaturesTemporaryToggle = 1 so Outlook does not overwrite signatures from the cloud.

Everything is in the user's own profile and HKCU, so no admin rights are needed at run time. Log and state: %LOCALAPPDATA%\SignetMail\agent.log and state.json.

#Install

Download the agent package (SignetMail.Agent.exe, install.ps1, uninstall.ps1) from the project's CI artifact signetmail-agent-win-x64, then on a PC as administrator:

.\install.ps1 -ApiUrl https://<host>/

The script copies the agent to C:\Program Files\SignetMail\Agent and creates the scheduled task \SignetMail\SignetMail Agent, which runs for each user at sign-in and then every 4 hours.

Intune: package as a Win32 app with install command powershell -ExecutionPolicy Bypass -File install.ps1 -ApiUrl https://<host>/ and uninstall command uninstall.ps1.

#Manual test

SignetMail.Agent.exe --api-url https://<host>/ --dry-run
type %LOCALAPPDATA%\SignetMail\agent.log

Arguments: --config <path>, --api-url <url>, --force (write regardless of hash), --dry-run (change nothing).

#Kerberos on the server side

The agent authenticates with the user's Windows credentials. This needs a server that is part of your domain, so the cloud setup described in this documentation (internet-facing, Entra ID only) is not used for the agent. Use deploy/docker/docker-compose.yml on a domain server instead:

1. Register a Service Principal Name for the service account running the API:

   setspn -S HTTP/signetmail.corp.example DOMAIN\svc-signetmail
   

2. Provide a keytab for that SPN to the container (KRB5_KTNAME).
3. Point the agent's -ApiUrl at that name.

Without a correct SPN, Windows falls back to NTLM or sign-in fails.

Tip. If all your users can use the add-in (new Outlook, web, Mac) you can skip the agent entirely. If you have classic Outlook but no domain, the add-in with Outlook on the web is the supported route.

#Transport rule for mobile devices

Exchange Online can append the signature on the server for messages that no add-in touched.

• The add-in adds an X-SignetMail header to every message it signs.
• The rule from deploy/exchange/Set-SignetMailTransportRule.ps1 adds the signature only to messages without that header, so nothing is signed twice.

Connect-ExchangeOnline
# 1. Audit mode (only records matches in the message trace), pilot group only, dry run first
.\Set-SignetMailTransportRule.ps1 -SenderGroup signetmail-pilot@example.com -Mode Audit -WhatIf
.\Set-SignetMailTransportRule.ps1 -SenderGroup signetmail-pilot@example.com -Mode Audit
# 2. Check the message trace, then enforce
.\Set-SignetMailTransportRule.ps1 -SenderGroup signetmail-pilot@example.com -Mode Enforce

#Limits set by Exchange

• The signature lands at the bottom of the whole message (below quoted text), and the sender does not see it while writing.
• It uses a short fixed layout with Exchange tokens (%%DisplayName%%, %%Title%%, %%Company%%, %%Department%%, %%Phone%%, %%MobilePhone%%, %%WindowsEmailAddress%% …) filled from Entra ID/AD; an empty value leaves an empty line. You can supply your own HTML with -DisclaimerHtmlPath; the script rejects unknown tokens and HTML over 5000 characters. -ExternalOnly limits it to external recipients, -ShowParameters prints what would be created without touching Exchange.
• Signed or encrypted messages stay unsigned (ApplyHtmlDisclaimerFallbackAction Ignore).
• It does not cover users of the Windows agent (the agent cannot add the header, so they would get two signatures). Limit the rule with -SenderGroup to people who use the add-in.

#Choosing a combination