#How SignetMail works

This page explains the moving parts and the life of a signature, from a change in Entra ID to the text at the bottom of an e-mail. Understanding it makes every setting in the rest of the documentation easier to follow.

#Architecture

Data flows left to right: the directory feeds the server, the server hands the finished signature to whichever channel the sender uses.

#The life of a signature

Directory sync. The server reads users (and, if configured, groups and their members) from Entra ID through Microsoft Graph. It does this at start-up and then every 60 minutes (SignetMail:Directory:SyncIntervalMinutes). Directory data is held in memory; nothing about your users is written to the database except access grants and statistics.
A user writes an e-mail. The Outlook add-in (or the Windows agent) asks the server: "what is the signature for me?" The request is authenticated — the add-in uses the user's Outlook sign-in, the agent uses Kerberos.
Choosing the template. The server evaluates the rules in order of priority. The first enabled rule whose audience matches the user and whose signature has a published version wins. A running campaign may add a banner. If nothing matches, the default signature applies.
Rendering. The published version of the template is rendered with Liquid using two data sets: user.* (from the directory) and org.* (from the organization chosen by the rule). All values are HTML-encoded automatically.
Delivery. The server returns the HTML, a plain-text version and a hash. The add-in inserts it into the message; the agent writes it into the Outlook signature folder only when the hash has changed.
Statistics. If a campaign banner was inserted, a daily counter is incremented. Clicks on the banner pass through /c/<id> on your server, which counts the click and redirects.

Note. Users always receive the published version. Anything being edited in a draft, or waiting for review, has no effect on real e-mails until an administrator publishes it.

#Key concepts

Concept	Meaning
Organization	A node in a tree (for example Group → Company). Holds the data used as `org.*` in templates — name, address, logo, colour and any custom fields — and is the unit of access control. Children inherit data from their parent.
Signature (template)	A named design with up to four parts: new mail HTML and text, reply HTML and text. Lives in an organization and can be used by that organization and everything beneath it.
Version	Each publication of a signature creates an immutable, numbered version. Only one version is live. You can preview any version and restore it into a draft.
Draft	The working copy. Saving a draft never changes what users receive.
Rule	Connects an audience (who) to a signature and an organization (whose data). Rules have priorities and optional validity periods.
Campaign	A banner with a link, shown in selected people's signatures during a period.
Role	Viewer, Editor, Admin or Owner, granted on the whole system, an organization (and everything below it) or a single signature. See Access and roles.
Hash	A fingerprint of the rendered signature. It changes only when the content changes, so agents and add-ins can skip needless rewrites.

#What runs where

SignetMail is a single containerised web application plus a reverse proxy:

API container (signetmail-api): ASP.NET Core application. It serves the portal (/portal/), the Outlook add-in (/addin/), this documentation (/docs/), the API (/api/…), uploaded logos (/uploads/…), campaign redirects (/c/…) and a minimal health check (/health).
Caddy container: terminates HTTPS, obtains and renews Let's Encrypt certificates automatically, and forwards requests to the API.
Database: SQLite file in the data/ folder by default (PostgreSQL is supported for larger installations).
Microsoft Entra ID: identity provider for sign-in and the source of directory data.

Everything is reachable on a single host name, which keeps certificates, firewalling and the Outlook add-in manifest simple.