#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.
| Channel | Works in | Where the signature appears | Needs |
|---|---|---|---|
| Outlook add-in | New Outlook for Windows, Outlook on the web, Outlook for Mac | Inserted into the message while composing; user sees it | Add-in deployment, Entra redirect URI |
| Windows agent | Classic Outlook for Windows | Written into Outlook's signature folder; user sees it | Install on PCs; Entra sign-in (Entra-joined or hybrid PCs) or Kerberos (domain) |
| Transport rule | Any client, including mobile apps | Appended by Exchange on the server; sender does not see it | Exchange Online admin |
Automatic insertion by the add-in in Outlook for iOS/Android is in progress (public beta), and the built-in mail apps never run add-ins. Until then the transport rule covers messages sent from phones.
#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.
- Embedded logo. Images uploaded to SignetMail are attached inline (
cid:), so recipients see the logo without clicking Download pictures. If the client cannot do that, the linked version is inserted. SeeEmbedImagesin Configuration. - No duplicates. The add-in marks messages with an
X-SignetMailheader 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. For classic Outlook for Windows use the Windows agent.
#Prerequisites
In the Entra app registration the redirect URI brk-multihub://<host> must exist (see Entra setup).
#Deploy to the tenant
- Open Microsoft 365 admin center → Settings → Integrated apps → Upload custom apps.
- App type Office Add-in, choose Provide link to manifest file and enter
https://<host>/addin/manifest.xml. - Assign it to the users. Start with a pilot group, then everyone.
- 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
- Open a new message — the signature should appear within a moment.
- Click Signature on the ribbon to see the pane with preview and hash.
- 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:
- Requests
newandreplysignatures from the server as the signed-in user (Kerberos; no passwords). - If the hash changed or files are missing, writes into
%APPDATA%\Microsoft\Signatures:SignetMail.htm,SignetMail.txt,SignetMail.rtfand the same forSignetMail Reply. - Sets
NewSignatureandReplySignatureinHKCU\Software\Microsoft\Office\16.0\Common\MailSettings. - Sets
DisableRoamingSignaturesTemporaryToggle = 1so 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.
#Sign-in
The agent signs in to the server as the user who is signed in to Windows, without passwords:
auth |
How | Use for |
|---|---|---|
auto (default) |
Entra ID first, Kerberos if that is not available | Most cases |
entra |
Entra ID token through Windows (Web Account Manager); the server address comes from the agent's config and the sign-in settings from the server | PCs joined to Entra ID (no domain), hybrid PCs, and a hosted server |
kerberos |
Windows domain sign-in (Negotiate) | Domain PCs with the server in the same domain |
Entra sign-in needs the redirect URI ms-appx-web://microsoft.aad.brokerplugin/<client-id> (see Entra setup). If the silent sign-in fails, run the agent once by hand with --sign-in; it then shows the Windows sign-in window.
#Install
Download SignetMail-Agent-win-x64.zip (contains SignetMail.Agent.exe, install.ps1, uninstall.ps1) from the latest release, unpack it, then on a PC as administrator:
.\install.ps1 -ApiUrl https://<host>/ -Auth auto
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:
- Register a Service Principal Name for the service account running the API:
setspn -S HTTP/signetmail.corp.example DOMAIN\svc-signetmail - Provide a keytab for that SPN to the container (
KRB5_KTNAME). - Point the agent's
-ApiUrlat 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-SignetMailheader to every message it signs. - The rule from
Set-SignetMailTransportRule.ps1(in the latest release) 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.-ExternalOnlylimits it to external recipients,-ShowParametersprints 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
-SenderGroupto people who use the add-in.
#Choosing a combination
| Situation | Recommendation |
|---|---|
| Pure Microsoft 365, new Outlook / web / Mac | Add-in only. |
| Classic Outlook on domain PCs | Add-in for new Outlook users + Windows agent for classic. |
| Many people sending from phones | Add the transport rule for the add-in user group. |
| Pilot | A small Entra group of volunteers for the add-in assignment and the rule. |