Architecture, requirements, usage

Why parameters are in a separate document: There are many available parameters, default values are chosen wisely, and custom values usually do not change over the years.

🔗Architecture considerations

Most companies choose the same default setup:

• Primary device (managed): Where users do most daily email work.
• Secondary devices (often managed, sometimes unmanaged): Phones, tablets, occasional laptops, VDI sessions, or private devices.

🔗Step 1: Create signatures and out-of-office replies

Set-OutlookSignatures comes with client mode, the Benefactor Circle add-on adds SimulateAndDeploy mode.

With the Benefactor Circle add-on, both modes can set out-of-office replies for internal and external recipients and also deploy signatures for mailboxes (and other Exchange recipient objects) the user can act as, even if they are not added as full mailboxes in Outlook (see the VirtualMailboxConfigFile parameter for details).

🔗Step 2: Make signatures available

• Client mode automatically updates the local Outlook signature store.
• SimulateAndDeploy has no access to end user devices and therefore treats Outlook for the web as the “local Outlook”.

With the Benefactor Circle add-on active, both modes can additionally make signatures available via multiple channels:

• Outlook for the web: On-prem supports one signature (new email preferred). Cloud combines with roaming signatures.
• Roaming Signatures;: Exchange Online feature; stores multiple signatures in the mailbox.
• Outlook Add-in: For Android, iOS, and unmanaged BYOD devices; automatic signature selection based on sender and rules.
• Draft Email: Universal compatibility via copy-paste; stores all signatures in HTML and plain text in Drafts.
• Documents Folder: Exports signatures to a local path (e.g. OneDrive-synced) for easy access in non-Outlook clients.

🔗Requirements and usage

🔗Linux and macOS

Not all features are yet available or possible on Linux and macOS. Every parameter contains appropriate information; the most important restrictions are summarized here.

🔗Security considerations

The security model of Set-OutlookSignatures and the Benefactor Circle add-on is built on the principles of Digital Sovereignty, Least Privilege, and Need to Know.

• In client mode for on-premises mailboxes, no additional permissions or Graph registrations are required.
• In Exchange Online, permissions are limited to the required Graph endpoints.

🔗Signature and OOF template file format

Word DOCX files or HTML files with extension .htm.

The name of the signature template file without extension is the name of the signature in Outlook: The template Test signature.docx becomes the signature with the name Test signature. This can be overridden in the INI file with OutlookSignatureName:

[Test signature.htm]
OutlookSignatureName = Test signature, do not use

🔗Proposed template and signature naming convention

A consistent naming convention helps both template maintainers and end users. One popular approach:

• Company
• Internal/External (int/ext)
• Language (two-letter code)
• Formal/Informal (frml/infrml)
• Optional mailbox hint (shared/delegate)

This is a recommendation; choose what fits your organization best.

🔗Replacement variables

Replacement variables are case-insensitive placeholders in templates that are replaced with user or mailbox values at runtime.

• Replacement happens everywhere, including hyperlinks and image alternative text.
• Variables can come from Active Directory, Entra ID (Graph), or any custom source via script logic.
• Custom variables are supported via a custom replacement variable config file.

Replacement variables do not just provide static text values, they can deliver dynamic content based on freely definable conditions and even influence the design of your signature. Examples are conditional banners, conditional texts, or account pictures.

Each replacement variable is available in four namespaces:

Set-OutlookSignatures comes with a big set of default replacement variables, covering more than most companies ever need for their signatures. Instead of providing a long list here, we provide the Test all default replacement variables signature, which not only shows all placeholders but also account pictures, conditional banners, QR codes and more. There are three ways to get there:

• View the template in DOCX format or in HTML format on GitHub or in the .\sample templates folder of your download.
• See the final result, i.e. your real values instead of the placeholders, after running the Quickstart guide. Just create a new email and select the generated sample signature “Test all default replacement variables”.
• Click here to view the "Test all default replacement variables" signature filled with data from our demo environment.

🔗Photos (account pictures, user image) from Active Directory or Entra ID

The software supports replacing images in signature templates with actual user photos. These photos are per default taken from Entra ID and Active Directory, but you may also definitive alternative sources such as a file share, a SharePoint document library, a database, or a web service.

As with other variables, photos can be obtained from the currently logged-in user, its manager, the currently processed mailbox and its manager.

Set-Outlooksignatures comes with the following default replacement variables for handling account pictures:

• $CurrentUserPhoto$
• $CurrentUserPhotoDeleteEmpty$
• $CurrentUserManagerPhoto$
• $CurrentUserManagerPhotoDeleteEmpty$
• $CurrentMailboxPhoto$
• $CurrentMailboxPhotoDeleteEmpty$
• $CurrentMailboxManagerPhoto$
• $CurrentMailboxManagerPhotoDeleteEmpty$

Note: Exchange and Outlook do not yet support images in OOF messages.

Adding account pictures is simple:

• When using DOCX template files
  1. Add a shape or a placeholder image.
  2. Set its text wrapping to "inline with text".
  3. Apply Word image features such as sizing, hadow, glow or reflection.
  4. Add one of the account pictures replacement variables, such as $CurrentUserPhoto$, to the alternative text of the image or shape.
• Whe using HTML template files
  1. Just add an account picture replacement variable to the the src or alt property of a placeholder image.

Set-OutlookSignatures take care of replacing the placeholder image or filling the shape with the desired account picture.

If you choose the "DeleteEmpty" option (e.g $CurrentUserPhotoDeleteEmpty$), the image or shape is deleted if there is no account picture available.

🔗INI files and template tags

INI files are an easy way to define which templates are to be used for which mailboxes, groups or users.

Template tags define properties for templates, such as:

• Time ranges during which a template shall be applied or not applied
• Groups whose direct or indirect members are allowed or denied application of a template
• Mailbox email addresses which are allowed or denied application of a template
• Replacement-variable conditions that allow or deny application of a template
• Default signature selection for new mails and reply/forward
• OOF template target (internal/external)

Why INI (or TOML-style) configuration? We avoid modern formats like XML, YAML, or JSON because they rely on strict syntax (brackets, significant whitespace, commas) that is easily broken by non-IT staff. INI-style keeps common cases simple, human-readable, and easy to maintain without specialized database infrastructure.

Set-OutlookSignatures comes with an INI editor (.\sample code\IniEditor.html or set-outlooksignatures.com/inieditor) offering a much more than just editing:

• A single HTML file that runs locally, from a file share, or hosted on a web server.
• Create or modify signature and out-of-office (OOF) configuration files with ease.
• Integrated documentation provides a clear explanation for every line and setting in the INI file.
• Detects errors based on technical syntax and years of real-world support experience from the support teams of Set-OutlookSignatures and the Benefactor Circle add-on.
• Visualizes the exact processing order the engine will use for templates.
• Includes undo/redo history, dark/light mode, mobile/touch support, and automatic input file encoding detection.

🔗Allowed tags (common cases)

The following list focuses on the tags that are used most often.

• Time range: 202401010000-202401312359
  Use -: prefix to deny a time range: -:202402010000-202402282359
  Add Z to interpret as UTC: 202401010000Z-202401312359Z
• Group assignment: <Environment> <Group Name>
  Assign a template to mailboxes that are (direct or indirect) members of this group.
  When using the -GraphOnly true parameter, prefer Entra ID groups (EntraID <Group Name>), you can also use on-prem groups (<DNS or NetBIOS name of AD domain> <Group Name>).
  Use -: prefix to deny a group: -:<Environment> <Group Name>
• Mailbox email address: office@example.com
  Assign a template to a specific mailbox; use -: to deny: -:test@example.com
• Replacement variable condition: $SomeVariable$
  Apply only when the variable evaluates to true. Use -: to deny: -:$SomeVariable$
• Write protect (Windows Classic Outlook only): writeProtect
• Default signature: defaultNew, defaultReplyFwd
• OOF scope: internal, external

For a complete reference and examples based on real-world use cases, see the INI files in the sample templates folder.

Note: Tags are case-insensitive.

🔗How to work with INI files

1. Comments: lines starting with # or ;
2. Use the sample INI files shipped with Set-OutlookSignatures as a starting point (see sample templates folder)
3. Put file names (with extension) in square brackets:

    [Company external English formal.docx]
    defaultNew
   

4. One tag per line below the file section header.
5. When using INI files, tags in filenames are treated as part of the name, not as tags.
6. Use parameters to point to the INI file:
   • SignatureIniFile
   • OOFIniFile

Set-OutlookSignatures comes with an INI editor (.\sample code\IniEditor.html or set-outlooksignatures.com/inieditor) offering a much more than just editing:

• A single HTML file that runs locally, from a file share, or hosted on a web server.
• Create or modify signature and out-of-office (OOF) configuration files with ease.
• Integrated documentation provides a clear explanation for every line and setting in the INI file.
• Detects errors based on technical syntax and years of real-world support experience from the support teams of Set-OutlookSignatures and the Benefactor Circle add-on.
• Visualizes the exact processing order the engine will use for templates.
• Includes undo/redo history, dark/light mode, mobile/touch support, and automatic input file encoding detection.

🔗Signature and OOF application order

Set-OutlookSignatures knows which mailboxes a user added to Outlook, and in which order they are sorted. Signatures are applied mailbox by mailbox in this order.

Within each group, templates are sorted by SortOrder and SortCulture (if defined in the INI file).

Important consequence: A template is applied only to the mailbox with the highest priority allowed to use it, so lower-priority mailboxes do not overwrite signatures intended for higher-priority ones.

You can influence behavior with the MailboxSpecificSignatureNames parameter and with the OutlookSignatureName tag in the INI file.

OOF templates are applied only if the out-of-office assistant is currently disabled. If it is active or scheduled, OOF templates are not applied.

🔗Simulation mode

Simulation mode is enabled when the parameter SimulateUser is passed. It answers the question:

“What will the signatures look like for user A, when Outlook is configured for the mailboxes X, Y and Z?”

In simulation mode:

• Outlook registry entries are not considered
• Nothing is changed in Outlook or Outlook for the web
• Resulting signatures are written to the path defined by AdditionalSignaturePath

Minimal example:

& .\Set-OutlookSignatures.ps1 -SimulateUser "a@example.com" -SimulateMailboxes "a@example.com", "x@example.com" -AdditionalSignaturePath "c:\test"

SimulateMailboxes is optional but highly recommended.
SimulateTime can be used to test time-based templates.
See .\sample code\SimulationModeHelper.ps1 for helper logic.