Outlook add-in#

This documentation applies to Piler enterprise edition releases 2.2.4+

Revision #2

Publication date: 2026-OCT-17

The Piler Archive add-in brings the archive into Outlook. Users can check whether the message they are reading is archived, search the archive, read archived messages and restore them to their mailbox, without leaving Outlook.

The add-in is served by piler-ui itself, so there is nothing to install on the archive server besides enabling it. It's off by default.

What it does#

The add-in opens as a pane on the right side of Outlook:

Search: keyword search in the archive, like the search box of the web UI. An empty search lists the latest messages. The hits are listed 20 at a time, and the next 20 load as you scroll down.
Preview: click a hit to see its subject, sender, date and the beginning of its text. ← Back returns to the hits.
Open full message: opens the whole message in a large window, with its headers, body and attachments.
Restore to my mailbox: sends the archived message back to the user's mailbox.

Users see the same messages as in the web UI: the add-in uses their piler account and its permissions.

Supported clients#

The add-in is a standard Office add-in, one manifest for all these clients:

Client	Notes
Outlook on the web (Microsoft 365, Outlook.com)
New Outlook for Windows
Outlook for Mac
Classic Outlook for Windows (2016 or newer)
Exchange 2016/2019 Outlook on the web (OWA)	Add the OWA host to `OUTLOOK_ADDIN_FRAME_ANCESTORS`

The mailbox must support the Mailbox 1.5 requirement set (Microsoft 365, Outlook.com, Exchange 2016 or newer). Outlook mobile is not supported.

Requirements#

piler-ui must be reachable over HTTPS by the users' Outlook, with a certificate their browsers trust. Office doesn't load add-ins over plain http.
JWT_SECRET must be set: the add-in authenticates with short-lived API tokens.

Enabling the add-in#

Add to the piler-ui configuration (e.g. /etc/piler/piler-ui.env), then restart piler-ui:

OUTLOOK_ADDIN_ENABLED=true

Check that the manifest is served:

https://archive.example.com/outlook/manifest.xml

The manifest is generated for the host it's downloaded from: its URLs point to that host, and its ID is derived from it. Download it from the same URL the users use to reach piler.

If the public URL of piler is not https://<the host name in the URL>, e.g. it uses a non-standard port, or a reverse proxy rewrites the Host header, set it explicitly:

OUTLOOK_ADDIN_BASE_URL=https://archive.example.com:8443

Multi-tenant setup#

Every tenant hostname serves its own manifest, so each tenant installs its own copy of the add-in. To enable it for a single tenant only, set it in the tenant's settings instead of the global configuration:

UPDATE piler.tenant_settings
SET settings_json = JSON_SET(COALESCE(settings_json, '{}'), '$.outlook_addin_enabled', true)
WHERE tenant_id = 'customer1';

When the add-in is disabled, every /outlook/ URL returns 404.

Installing the add-in in Outlook#

For all users of a Microsoft 365 organisation#

Download the manifest from https://<piler host>/outlook/manifest.xml.
In the Microsoft 365 admin center, go to Settings → Integrated apps → Upload custom apps.
Choose Office Add-in, upload the manifest, and assign the add-in to all users or to some users or groups.

It can take up to 24 hours until the add-in appears in the users' Outlook.

Exchange 2016/2019#

In the Exchange admin center, go to Organization → Add-ins → + → Add from file, and upload the manifest.

Also add the OWA host to the origins allowed to show the add-in, e.g.:

OUTLOOK_ADDIN_FRAME_ANCESTORS=https://outlook.office.com https://outlook.office365.com https://outlook.live.com https://outlook.cloud.microsoft https://*.outlook.com https://*.office.com https://*.office365.com https://*.cloud.microsoft https://owa.example.com

For a single user (testing)#

Download the manifest.
Open https://aka.ms/olksideload. It opens Outlook on the web with the add-ins dialog.
Go to My add-ins → Custom Addins → Add a custom add-in → Add from File..., choose the manifest, and click Install.

The add-in is then available in every Outlook signed in with that account (on the web, new Outlook for Windows, Outlook for Mac).

To remove it, open the same dialog, and click ... → Remove next to Piler Archive under My add-ins.

Using the add-in#

Opening the add-in#

Open a received message, then:

Outlook on the web and new Outlook for Windows: click the Apps button in the action bar of the message (next to Forward), or on the ribbon, and choose Piler Archive.
Classic Outlook for Windows and Outlook for Mac: click Piler Archive on the Home ribbon.

The add-in is only offered for messages you are reading, not in the compose window.

Showing the Piler icon on every message#

In Outlook on the web and new Outlook for Windows, the add-in is under the Apps button by default. To have the Piler icon right next to Forward on every message:

Open a message, and click … (More actions) in its action bar, next to the Apps button.
Click Customize actions.
Under Add-ins, tick Piler Archive, and click Save.

One click on the icon then opens the pane. Each user sets this for their own mailbox; the manifest can't do it for them.

Signing in#

Click Sign in. A window opens with the usual piler login page, where you sign in as in the web UI, with any login method of your archive (local, LDAP, IMAP, SSO, passkey, two-factor authentication). The window closes by itself afterwards.

The add-in stays signed in for 15 minutes. After that, it asks you to sign in again. If your piler session is still valid, the sign-in window just closes without asking for your password.

Sign out in the top right corner of the pane signs the add-in out.

Searching#

Type the search terms, and click Search. Leave the field empty to list the latest messages. The search works like the simple search of the web UI.

Scroll down to load more hits, 20 at a time.

Reading a message#

Click a hit to open its preview. Open full message opens the whole message in a large window: the subject, From, To, Cc and Date headers, the message body, and the attachments, which you can download.

For safety the message window, like the web UI, does not run scripts in the email, does not load images from external websites, and does not open the links of the email.

Restoring a message#

Click Restore to my mailbox in the preview. Piler sends the archived message to your email address, and it arrives in your mailbox shortly. Restoring requires the restore permission.

Configuration options#

Option	Default	Description
`OUTLOOK_ADDIN_ENABLED`	`false`	Enables the add-in. Can be set per tenant.
`OUTLOOK_ADDIN_BASE_URL`	`""`	The public URL of piler-ui used in the manifest. Empty means `https://` + the host the manifest is downloaded from.
`OUTLOOK_ADDIN_FRAME_ANCESTORS`	Microsoft 365 and Outlook.com origins	Space separated list of the origins allowed to show the add-in pane. Append the host of an on-premises OWA.
`OUTLOOK_ADDIN_RELAX_LOGIN_COOP`	`true`	Needed for the sign-in in Outlook on the web, see Security.

Security#

The add-in pane never gets the piler session cookie. After signing in, the sign-in window hands it an API token of the signed in user, valid for 15 minutes. Only piler's own pages can request such a token. Issuing a token is written to the audit log.
The add-in asks Outlook for the lowest permission (Restricted): it doesn't read the messages of your mailbox, and sends nothing about them to piler.
Every request of the add-in goes through the same permission checks as the web UI, and viewing a message is audited the same way.
Only the Outlook origins in OUTLOOK_ADDIN_FRAME_ANCESTORS may show the add-in pages. The rest of the web UI still can't be embedded in other sites.
In Outlook on the web the sign-in window is a popup that reports back to the add-in pane. To make that possible, piler relaxes the Cross-Origin-Opener-Policy header of the login pages, but only while a sign-in started from the add-in is in progress (at most 10 minutes, in that browser). Regular logins keep the strict header. Set OUTLOOK_ADDIN_RELAX_LOGIN_COOP=false to switch this off, if your users only use desktop Outlook clients.
If your single sign-on provider sends a strict Cross-Origin-Opener-Policy header on its own pages, signing in from Outlook on the web may not finish with that provider.

Troubleshooting#

The add-in does not appear in Outlook

Open a received message: the add-in is not offered in the message list or in the compose window.
In Outlook on the web, look under the Apps button, or pin the icon, see Showing the Piler icon on every message.
After an organisation-wide deployment, wait up to 24 hours.
Check that https://<piler host>/outlook/manifest.xml downloads. A 404 means the add-in is not enabled for that host.

The pane stays empty

The certificate of piler must be trusted by the browser.
Browser privacy features or ad blockers may block the Office script (appsforoffice.microsoft.com) the pane needs. Allow it for the Outlook site.
On an on-premises OWA, add its host to OUTLOOK_ADDIN_FRAME_ANCESTORS.

Sign in or Open full message does nothing

Both open a popup window. Allow popups for the Outlook site in the browser.

Limitations#

English only.
The preview in the pane shows the beginning of the text. The full message window shows the whole message, but not the extras of the web UI (notes, tags, threads, PDF export).
The width of the pane is set by Outlook, the add-in can't change it.
No compose features, and no mailbox stubbing.