Outlook on Windows

This guide adds the TrustDID Outlook add-in on Windows. You'll end up with a TrustDID group on the ribbon — Sign Documents in the compose view and Verify Signatures in the read view — talking to the TrustDID service running on your own machine.

Requirement — a Microsoft 365 / Exchange mailbox. Outlook add-ins (this is a "web add-in") only load for Exchange Online / Microsoft 365 or on-premises Exchange accounts. They are not supported on POP/IMAP mailboxes — generic ISP or webmail accounts (e.g. most @videotron.ca, @gmail.com, cPanel hosting). On those accounts Outlook doesn't even show the "Add a custom add-in" option. If your mailbox isn't on Exchange/M365, use the CLI (trustdid sign / trustdid verify) or the Thunderbird/browser plugins instead.

Before you start

You need:

A Microsoft 365 / Exchange mailbox configured in Outlook (see the requirement above).
The TrustDID software bundle installed — run the setup.exe installer. On Professional and up it places the add-in files at C:\Program Files\TrustDID\outlook-plugin\. See Software Bundle on Windows if you haven't done that yet.
An activated identity — for paid tiers you've run trustdid-setup --managed YOUR_TOKEN YOUR_ID (token and UUID come from your enrolment email; it pulls your license automatically). Free-tier users get a public test identity. Confirm with trustdid status.
The TrustDID Service running — the installer registers it as a Windows service that auto-starts. Confirm with trustdid-service status.

The add-in talks to the service over https://localhost:8080 (API) and https://localhost:8000 (the add-in's pages). Both ports must be free.

Step 1: Verify the service is up

Open https://localhost:8080/health in a browser. Accept the local TrustDID self-signed certificate the first time — you should then see a small JSON response with "status": "ok".

If you get "connection refused", the service isn't running. Start it from a terminal:

trustdid-service status
            trustdid-service start

Step 2: Add the add-in to Outlook

The add-in is a small XML manifest that points at the service on your machine. The software-bundle installer already placed it here:

C:\Program Files\TrustDID\outlook-plugin\manifest.xml

Install it once per Outlook profile:

In Outlook, open Home → Get Add-ins (or File → Manage Add-ins), then choose My add-ins.
Scroll to Custom Addins and click Add a custom add-in → Add from File.... (If you don't see this option, either your mailbox isn't an Exchange/M365 account — see the requirement at the top — or your organisation doesn't let users add their own add-ins: see For Microsoft 365 administrators.)
Browse to C:\Program Files\TrustDID\outlook-plugin\manifest.xml and open it.
Confirm the warning prompt — click Install.

The TrustDID group with Sign Documents and Verify Signatures buttons now appears on the ribbon, in both the compose and read views.

Don't move or delete C:\Program Files\TrustDID\outlook-plugin\. Outlook loads the add-in's pages from there (through the local service) every time it runs, so the files must stay where the installer put them. If you instead downloaded the standalone TrustDID-Outlook plugin .zip, extract it to a permanent folder and point Add from File at that manifest.xml — same rule: don't move the folder afterward.

Step 3: Sign your first email

Click New Email.
Compose a short message. The TrustDID group is on the ribbon.
Click Sign Documents. A footer signature line is appended to the message, and your attachments are signed.
Send. The recipient gets the email plus a .vrfy sidecar.

Step 4: Verify a received email

Open a signed message and click Verify Signatures. The task pane shows a result within a second or two, answering two independent questions:

Document authenticity — "Is it genuine?" (Verified / Inconsistent / Failed / Unsigned)
Green shield — authenticity Verified: the signature verifies, the sender's DID is published, and the sender's email matches the From header.
Amber shield — the signature verifies but something else is off (for example the From header was rewritten by a mailing list).
Red shield — authenticity Failed, or the sidecar is missing (Unsigned).
Trusted signer — "Who vouches for it?" (Yes / No / Unknown) — based on the trust registries your verifier is configured with (trustdid-setup --add-trusted-registry). An authentic message from a signer none of your registries vouch for is a normal outcome — genuine, but untrusted until someone you trust vouches for the sender.

Click the shield for the full verification trace.

Troubleshooting

"Add a custom add-in" isn't in the menu. There are two causes. If the account is POP/IMAP, add-ins aren't supported at all — the add-in needs an Exchange Online / Microsoft 365 mailbox. If it is a work Microsoft 365 account (the option shows up for a personal outlook.com account in the same Outlook but not for the work one), your organisation has turned off user-installed add-ins. Nothing you install locally changes that: ask your Microsoft 365 administrator to deploy the add-in for you — see For Microsoft 365 administrators.

Outlook says "TrustDID Sign & Verify is unavailable" when you send. TrustDID isn't running on this computer. Choose Send Anyway to send the email unsigned, then see Outlook add-in — when TrustDID isn't running.

"Couldn't load the add-in" when installing. The TrustDID Service isn't running, or port 8000 is blocked. Check https://localhost:8000/commands.html in your browser — you should see a page, not an error. Start the service with trustdid-service start.

Sign button stays grey / does nothing. Identity isn't configured. Run trustdid status and trustdid-service status — they tell you whether the identity file is missing or the license is expired.

Verification task pane shows "service unreachable". The service stopped, or antivirus/firewall is blocking https://localhost:8080. Add an exception for C:\Program Files\TrustDID\.

New Outlook / Outlook on the web doesn't show the buttons. The local "Add from File" install is for classic Outlook desktop. For new Outlook and Outlook on the web, have your Microsoft 365 administrator deploy the add-in centrally — see For Microsoft 365 administrators.

What's installed

The software-bundle installer lays the add-in down here:

C:\Program Files\TrustDID\outlook-plugin\
            ├── manifest.xml        The add-in manifest you point Outlook at
            ├── commands.html / .js Sign / auto-sign-on-send logic
            ├── verify.html         Verification task pane
            ├── settings.html       Add-in settings
            └── assets\             Ribbon icons

These pages are served to Outlook by trustdid-service.exe at https://localhost:8000; the CLI and service themselves live in C:\Program Files\TrustDID\ (see the Software Bundle on Windows guide).

For Microsoft 365 administrators

In most organisations users can't add their own add-ins: the Add a custom add-in option is simply missing from their Outlook. As a Microsoft 365 administrator you have two ways to make TrustDID available. Option A is the one we recommend.

Whichever you choose, the add-in only adds the TrustDID buttons to Outlook. Signing and verification are done by the TrustDID software on each user's own computer, so every user who needs the buttons must also have the Software Bundle installed, an activated identity and the TrustDID Service running (see Before you start). Their private keys never leave their computer.

Option A: deploy the add-in centrally (recommended)

The add-in appears in Outlook for the people you choose, with nothing for them to install in Outlook. It also works in new Outlook and Outlook on the web.

Take the manifest from any computer with TrustDID installed: C:\Program Files\TrustDID\outlook-plugin\manifest.xml.
Sign in to the Microsoft 365 admin center (https://admin.microsoft.com) with a Global or Exchange administrator account.
Go to Settings → Integrated apps, then click Upload custom apps.
Choose Office Add-in, select Upload manifest file (.xml) from device, pick manifest.xml, and click Next.
Choose who gets it: Just me (a good first test), Specific users/groups (for example the group of people who sign on behalf of the organisation), or Entire organization. Click Next.
Review the permissions and click Accept permissions, then Finish deployment.

Deployed add-ins usually show up in Outlook within a few hours, but Microsoft says it can take up to 72 hours. Users may need to restart Outlook. They can't remove an add-in you deployed, and you can change who gets it, or remove it, from the same Integrated apps page.

When a TrustDID release changes manifest.xml (the release notes say so), open the add-in in Integrated apps, choose Update add-in and upload the new file. Releases that only change the add-in's pages need nothing from you: they are updated on each computer by the Software Bundle installer.

Option B: let users add it themselves

Users get back the Add a custom add-in → Add from File option and follow Step 2 themselves. This works in classic Outlook desktop only, and it lets users add any add-in, not only TrustDID. Many organisations turn it off for that reason.

The option is controlled by the user roles in the mailboxes' role assignment policy. Users need My Custom Apps, and also My ReadWriteMailbox Apps because the TrustDID add-in asks for read/write access to the mailbox.

Sign in to the Exchange admin center (https://admin.exchange.microsoft.com).
Go to Roles → User roles and open the policy your users have (usually Default Role Assignment Policy).
Click Manage permissions, tick My Custom Apps and My ReadWriteMailbox Apps, and click Save changes.

The change can take an hour or so to reach users. To do the same in Exchange Online PowerShell (Connect-ExchangeOnline first):

Get-Mailbox user@example.org | Format-List RoleAssignmentPolicy
            New-ManagementRoleAssignment -Role "My Custom Apps" -Policy "Default Role Assignment Policy"
            New-ManagementRoleAssignment -Role "My ReadWriteMailbox Apps" -Policy "Default Role Assignment Policy"

Replace Default Role Assignment Policy with the name the first command shows if your users have a different policy.

Need help?

Contact support@trustdid.ca with the output of trustdid-service status and your Outlook version (File → Office Account → About Outlook). We respond within one business day for Professional and faster for Business.