Support — fa for Outlook
fa lives in your mailbox as a taskpane chat with three approval-gated mail tools: read the open email, read its attachments, write draft bodies. This page is the install guide.
Requirements
- An Outlook account: personal (outlook.com) or work/school. Org tenants must allow custom add-ins — see troubleshooting if yours doesn't.
- Any of: Outlook on the web (outlook.office.com / outlook.live.com), new Outlook for Windows, or classic Outlook for Windows / Mac.
- The manifest:
https://fa1.dev/outlook/manifest.xml— currently 1.1.0.0, the VersionOverrides release from issue #143, which surfaces everywhere including the Apps-flyout button in new Outlook. Installs from the earlier 1.0.0.0 show no fa entry in new Outlook — re-install from the current manifest (see troubleshooting).
1. Download the manifest
Save https://fa1.dev/outlook/manifest.xml
as manifest.xml (right-click → Save link as…, or
Ctrl+S / Cmd+S on the page). If the browser shows the XML as text,
save the page source; don't let the file become
manifest.xml.txt.
Why download instead of URL: Microsoft removed the manual “Add from a URL” entry from the add-ins dialog, so download-then-file is the only self-service install path.
2. Open the add-ins manager
The reliable entry on every surface is Microsoft's deep link: https://aka.ms/olksideload — it opens Outlook's My add-ins dialog directly. Sign in with the same account you read mail with.
Manual alternatives (same dialog, more clicks):
- Outlook on the web / new Outlook: open a message, then the Apps flyout in the reading-pane toolbar → Get add-ins. Note: new Outlook's main Settings page has no add-ins section — the Apps flyout on a message is the entry.
- Classic Outlook (Windows/Mac): ribbon Home → Get Add-ins (or File → Manage Add-ins), then the My add-ins tab.
3. Install from file
In the dialog: My add-ins → Custom add-ins →
“+ Add a custom add-in” → Add from file → pick the
downloaded manifest.xml → Install. Accept the
trust prompt (“This add-in is not from the App Store”) with
Install.
The add-in now appears under My add-ins → Custom add-ins as fa.
4. Open the taskpane
Open (or select) any email message, then:
- New Outlook for Windows / Outlook on the web: the message's Apps flyout (toolbar or ⋯ menu) → fa; in a compose window the flyout sits in the compose toolbar. (Needs manifest 1.1.0.0 — the VersionOverrides release, issue #143. If you installed 1.0.0.0 earlier: remove the add-in, re-download the manifest, re-add from file; Outlook may cache the old version up to 24 h.)
- Classic Outlook for Windows: Home ribbon → fa button.
- Classic Outlook for Mac: the message ribbon → fa.
Configure a provider and API key inside the pane (BYOK — the key stays in the add-in's local storage). Reading a mail body or attachment always prompts for approval. To remove: My add-ins → Custom add-ins → ⋯ on fa → Remove.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
| “Installation failed — Add-in installation failed.” on upload | The manifest failed validation. This was a real manifest defect before v1.0.0.0 finished deployment (#131/#133 — an XML comment bug, since fixed; Microsoft's validation gateway now accepts the manifest). Re-download manifest.xml and retry; make sure the file wasn't saved as .txt or truncated. |
| No Custom add-ins section, or “installing from url is disabled” | Your tenant blocks custom add-ins (common in corporate tenants). An admin can deploy fa via the M365 admin center (Settings → Integrated apps → Upload custom apps), or install with a personal Outlook.com account instead. |
| Installed but no fa button anywhere in new Outlook | You're running the pre-#143 1.0.0.0 manifest — it has no ribbon surface in new Outlook. Re-download the manifest (check <Version> — 1.1.0.0), remove the old add-in (My add-ins → Custom add-ins → ⋯ → Remove), re-add from file. Classic Outlook works on either version; Outlook may cache the old one up to 24 h. |
| Old version keeps running after an update | Outlook caches add-ins for up to 24 h (classic Windows). Remove the add-in, re-add from the new manifest, restart Outlook; worst case wait out the cache. |
| “host API unavailable” banner in the taskpane | The Office.js runtime did not load. Reload the taskpane; if it persists, the pane answers without mail tools. |
| Taskpane blank | Make sure your network allows fa1.dev and the Office.js CDN (appsforoffice.microsoft.com) — check proxies and corporate filters. |
Full guide with the same steps in the repository: docs/outlook-addin.md.
Dev copy
bash scripts/build_office_addin.sh --dev produces a manifest pointed at https://localhost:8443.
Contact
Still stuck? Mail support@fa1.dev and include your Outlook host (web / Windows / Mac) and the version shown in the taskpane.