4.1. Add-in manifest

site/manifest.xml is the file that Outlook reads to learn where the task pane is hosted, what icons to show, and which permissions the add-in requires. Everything else in the bundle (JS, HTML, icons) is static content that is simply served over HTTPS - only the manifest needs per-customer editing.

4.1.1. The host placeholder

The released manifest ships with a sentinel hostname https://TOA_HOST_PLACEHOLDER/ in every absolute URL it declares. That single string is rewritten to the customer’s real HTTPS origin by the apply-host helper included in the bundle:

# POSIX
$ chmod +x apply-host.sh
$ ./apply-host.sh https://addin.customer.cz/

# Windows
PS> .\apply-host.ps1 -HostUrl https://addin.customer.cz/

The script is idempotent-hostile on purpose: if the placeholder is no longer present, it exits non-zero. This prevents accidentally running it twice and leaving a half-substituted manifest. Re-extract the original ZIP when you need to re-run.

The chosen hostname must:

  • be reachable over HTTPS with a publicly trusted certificate - Outlook refuses self-signed certs outside the localhost dev flow;

  • serve the site/ contents at its root (/taskpane.html, /assets/...);

  • reverse-proxy /api/* to the TOA server (see Hosting the task pane).

4.1.2. Values that change per release

These fields are updated automatically by the release build and should not be hand-edited by operators:

<Version>

Incremented on each release. Outlook uses this to detect new manifests and re-download the bundle.

<bt:Image ...>, <bt:Url id="Taskpane.Url">

Default values point at the host placeholder; the apply-host script rewrites them.

4.1.3. Values that are stable across releases

<Id>

The manifest GUID. It is deliberately kept stable between releases: rotating it would force every user to re-install the add-in. Rotate only when the requested <Permissions> level changes, so that Outlook’s TitleId-backed sideload cache registers the new capabilities.

<Requirements><Set Name="Mailbox" MinVersion="1.15"/></Requirements>

Mailbox 1.15 is required so the add-in can read the full RFC 822 MIME of the current message via MessageRead.getAsFileAsync. Hosts that do not meet this version refuse to install the add-in (clean failure instead of a silently-missing method).

<Permissions>ReadWriteItem</Permissions>

The minimum needed for the current feature set. The add-in only reads the active message and writes roaming settings - it does not need ReadWriteMailbox. Raising the permission level in the future requires also rotating <Id>.