So where do you put it? localStorage is per-device, per-browser, and mobile WebViews evict it whenever they feel like it. A backend with a database is a lot of infrastructure for one JSON file per user. And then it hit me: every single one of my users already has cloud storage my add-in can reach. Their OneDrive.

What the App Folder Actually Is

First time your app touches approot, OneDrive creates a folder under Apps/<your app's name> (the name comes from your Entra app registration). It’s the user’s storage, visible to them in OneDrive, but sandboxed for you: request Files.ReadWrite.AppFolder and that folder is all your app can see. No scary “this app can read all your files” consent screen.

One endpoint to remember:

/me/drive/special/approot

Saving Settings

I use PnPjs (@pnp/graph), so a save is three lines:

import { SpecialFolder } from "@pnp/graph/files";

async function saveUserSettings(settings: UserDefinedSettings): Promise<void> {
  const appRoot = graphFI.me.drive.special(SpecialFolder.AppRoot);
  await appRoot.upload({
    content: JSON.stringify(settings),
    filePathName: "user-settings.json",
    contentType: "application/json",
  });
}

No PnPjs? The raw Graph equivalent is a single PUT: PUT /me/drive/special/approot:/user-settings.json:/content.

Reading Settings (and Surviving the First Run)

Reading has one twist: the very first time a user opens your add-in, the file doesn’t exist yet. That’s not an error, that’s a new user. Plan for it:

const defaultSettings: UserDefinedSettings = {
  openPreviewInNewTab: false,
  returnToHomeAfterArchive: false,
  hasSeenPinTip: false,
};

async function getUserSettings(): Promise<UserDefinedSettings> {
  try {
    const appRoot = graphFI.me.drive.special(SpecialFolder.AppRoot);
    const children = await appRoot.children();
    const fileItem = children.find((item) => item.name === "user-settings.json");

    if (!fileItem) {
      return defaultSettings; // first run - no file yet
    }

    const blob = await graphFI.me.drive.getItemById(fileItem.id!).getContent();
    const json = JSON.parse(await blob.text());

    return {
      openPreviewInNewTab: json.openPreviewInNewTab ?? defaultSettings.openPreviewInNewTab,
      returnToHomeAfterArchive: json.returnToHomeAfterArchive ?? defaultSettings.returnToHomeAfterArchive,
      hasSeenPinTip: json.hasSeenPinTip ?? defaultSettings.hasSeenPinTip,
    };
  } catch (error) {
    console.error("Error getting user settings:", error);
    return defaultSettings; // any failure - the add-in still works
  }
}

What’s happening here?

1. Missing file → defaults, not an exception. New users get a working add-in, not an error toast.
2. Every field is parsed with a ?? fallback. When I ship a new setting next month, users with an old user-settings.json don’t break, the new field just gets its default.
3. The whole thing is wrapped in try/catch that returns defaults. Settings are a nice-to-have; they should never take the add-in down with them.

Two practical habits: load the settings once at boot and cache them (don’t re-read OneDrive on every render), and save optimistically - update your local state immediately, fire the upload without awaiting it. And the best part comes for free: change a setting on desktop, open the phone, it’s there. 🎁

Not Just Outlook Add-ins: SPFx Too

This pattern isn’t tied to Outlook at all, it just needs a user context and a Graph token. That makes it a great fit for SPFx web parts as well.

Web part properties in SPFx are per-instance and per-page, and usually something an editor configures, not the end user. If you want user-level preferences - a collapsed/expanded state, a preferred view, a dismissed banner - that follow the user across every page and site where your web part lives, the App Folder solves it with zero extra infrastructure. Grab MSGraphClientV3 from the SPFx context and hit the same /me/drive/special/approot:/user-settings.json:/content endpoint. Same folder, same JSON file, same permission model.

Gotchas

• Ask for Files.ReadWrite.AppFolder, not Files.ReadWrite. If the app folder is all you need, the scoped permission gets you a much friendlier consent prompt and a much smaller blast radius.
• The folder is named after your app registration’s display name. Rename the registration and users get a new empty folder, your settings file stays behind in the old one.
• Users can see (and delete) the folder. It’s their OneDrive. Treat a missing file as a normal state, always, not just on first run.

Wrapping Up

User preferences don’t need a database, and they deserve better than localStorage. The OneDrive App Folder is the middle ground that’s easy to miss: zero infrastructure on your side, real cloud persistence on theirs, and a permission model that only exposes what your app actually needs. Outlook add-in, SPFx web part, anything with a Graph token - same trick everywhere.

Then the user taps “Archive to SharePoint” and the whole feature stands on one API: getAsFileAsync(), which hands you the entire email as a file. That API lives in Mailbox 1.14. Outlook mobile doesn’t have it.

So now I had the opposite problem from last time: instead of an invisible add-in, I had a visible add-in with a dead button. Honestly, that’s worse.

Visible ≠ functional. This post is about the second half of the mobile story: getting the same email bytes through a different door.

The Desktop Path: Just Ask Outlook

On desktop and web, Office.js does all the work. You ask the host for the current message as a file, and it hands you the EML as base64. No network call, no token, no permissions dance, Outlook already has the email.

function getMessageAsBlob(): Promise<{ bytes: Uint8Array; blob: Blob }> {
  return new Promise((resolve, reject) => {
    if (!Office.context.requirements.isSetSupported("Mailbox", "1.14")) {
      return reject(new Error("This client does not support Mailbox 1.14 (getAsFileAsync)."));
    }

    const item = Office.context.mailbox.item as Office.MessageRead;
    item.getAsFileAsync((asyncResult) => {
      if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        return reject(asyncResult.error);
      }

      // getAsFileAsync returns the EML as base64
      const bytes = Uint8Array.from(atob(asyncResult.value), (c) => c.charCodeAt(0));
      const blob = new Blob([bytes], { type: "message/rfc822" });
      resolve({ bytes, blob });
    });
  });
}

Notice the first thing this function does: check isSetSupported("Mailbox", "1.14") and reject if it’s not there. That reject is not an error case, it’s a signal. Remember it, it becomes important in a minute.

The Graph Path: Ask Exchange Instead

Here’s the realization that saved the mobile experience: Outlook doesn’t own your email, Exchange does. The host app is just one way to get at it. Microsoft Graph is another, and Graph has an endpoint that returns the raw MIME content of any message:

async function getMessageAsBlobViaGraph(): Promise<{ bytes: Uint8Array; blob: Blob }> {
  const item = Office.context.mailbox.item as Office.MessageRead;
  if (!item?.itemId) {
    throw new Error("No item ID available for Graph-based archive.");
  }

  const token = await getToken(["Mail.ReadWrite.Shared"]);

  const mimeUrl = `https://graph.microsoft.com/v1.0/me/messages/${encodeURIComponent(item.itemId)}/$value`;
  const resp = await fetch(mimeUrl, {
    method: "GET",
    headers: { Authorization: `Bearer ${token}` },
  });

  if (!resp.ok) {
    throw new Error(`Error ${resp.status}: ${resp.statusText}`);
  }

  const buffer = await resp.arrayBuffer();
  const bytes = new Uint8Array(buffer);
  const blob = new Blob([buffer], { type: "message/rfc822" });
  return { bytes, blob };
}

What’s happening here?

1. item.itemId is all we need from Office.js, and reading it only requires Mailbox 1.1. That’s the beautiful part: the manifest floor from the last post promised almost nothing, and this fallback only needs almost nothing.
2. The $value segment on /me/messages/{id} tells Graph to skip the JSON representation and return the raw RFC 822 message, the same EML you’d get from getAsFileAsync.
3. We wrap it in a Blob with message/rfc822, the exact same shape the desktop path produces. Same email, different source.
4. The token comes from MSAL with the Mail.ReadWrite.Shared scope. And yes, getting a token inside Outlook mobile is its own adventure, the magic words are Nested App Auth (NAA), where sign-in goes through the Microsoft Authenticator app instead of a browser popup. That one deserves its own post someday.

One honest caveat: I pass item.itemId straight to Graph without converting it. That works because modern hosts (including mobile) hand out REST-format IDs. If your add-in also runs in older Outlook clients that still produce EWS-format IDs, run the ID through Office.context.mailbox.convertToRestId() first, or Graph will give you a very confusing 404.

Don’t Branch, Fall Back

So we have two functions. The tempting way to pick between them is if (isMobile) { ... } else { ... }. I did it differently, and I’m glad I did:

let messageAsBlob: { bytes: Uint8Array; blob: Blob };
try {
  messageAsBlob = await getMessageAsBlob();
} catch {
  // Office.js getAsFileAsync unavailable (e.g. mobile) - fall back to Graph
  if (getMessageAsBlobViaGraph) {
    messageAsBlob = await getMessageAsBlobViaGraph();
  } else {
    throw new Error("Email export is not available on this platform.");
  }
}

Always try Office.js first, and let the failure route you to Graph. Remember that reject on the 1.14 check? On mobile it fires every time, and the catch block quietly takes the Graph road instead.

Why is this better than platform-branching? Because it’s capability-based, not platform-based. If some desktop client out there is running an older Outlook without 1.14, it gets the fallback for free. I never had to predict which platforms are broken, the code just asks “did the good path work?” and moves on.

I do add one belt-and-suspenders detail: the Graph function is only injected into this flow when platform detection says we’re on mobile. On desktop it’s undefined, so a genuinely broken desktop fails loudly with a clear message instead of silently making Graph calls I didn’t expect.

Same Blob, Same Pipeline

This is the part I want you to steal. Both functions return the same thing:

{ bytes: Uint8Array; blob: Blob }  // type: "message/rfc822"

Everything after this point - naming the file, uploading it to SharePoint, progress reporting, conflict handling - is one code path. The upload logic has no idea whether the bytes came from Office.js or from a Graph call. There’s no if (isMobile) sprinkled through the upload code, no duplicated pipeline, nothing.

That’s the whole trick, really. A good fallback isn’t a second feature, it’s a second source feeding the same feature. The moment your fallback needs its own downstream handling, you’ve built two features and doubled your bugs.

Gotchas I Hit Along the Way

• ID formats will bite you. REST IDs and EWS IDs look similar enough (long base64-ish strings) that you won’t spot the difference by eye. If Graph returns 404 for a message you’re literally looking at, check the ID format before questioning your sanity. convertToRestId() is the fix.
• Graph only knows what the server knows. getAsFileAsync reads from the host, Graph reads from Exchange. For a message that just arrived, the server side can lag a beat behind what Outlook is already showing you. Rare, but real.
• No retry for free. Office.js calls fail locally and instantly. The Graph call is a network request that can hit throttling or transient errors, and a bare fetch won’t retry anything. Mine throws on non-OK responses and lets the surrounding archive flow surface the error; depending on your feature, a retry with backoff might be worth it.

Wrapping Up

The manifest post got the add-in through the door on mobile. This post made it actually earn its place there: use Office.js when the host can deliver, fall back to Graph when it can’t, and make both paths hand over identical bytes so the rest of your app never has to care.

Outlook is just one door to the mailbox. When it’s locked, Graph is around the back. 🚪

And in that second post I wrote one very casual line: “The token comes from MSAL.”

Yeah. About that.

On desktop, MSAL gets a token by opening a browser popup where the user signs in. On mobile there is no browser. Your add-in runs in a WebView inside the Outlook app. There’s no window to pop, no tab to redirect, nowhere for the classic OAuth dance to happen. My first attempt at calling Graph from the phone died right there, not on the API call, on the sign-in before it.

The fix has a name: Nested App Auth (NAA).

Why Normal MSAL Dies on Mobile

The standard MSAL flows (loginPopup, loginRedirect) both assume your code lives in a browser. A popup needs window.open. A redirect needs the page to navigate away to login.microsoftonline.com and come back with your app still knowing what it was doing.

Inside Outlook on iOS or Android, neither is true. You’re in a WKWebView (or the Android equivalent) that Outlook controls. window.open goes nowhere useful, and a redirect would navigate the task pane itself into oblivion.

But think about what’s around your WebView: the Outlook app. A fully signed-in, Microsoft-identity-aware native app that already knows exactly who the user is. NAA is the mechanism that lets your nested add-in say “hey host, you handle the identity stuff” and get tokens brokered through Outlook itself. When silent brokering isn’t enough, the host hands off to Microsoft Authenticator for the interactive part, a real native auth experience instead of a popup that can’t exist.

The Azure Part: One Weird Redirect URI

Before any code, your Entra app registration needs to opt in to being brokered. That’s done with a redirect URI of type Single-page application in this format:

brk-multihub://your-add-in-domain.com

Origin only, no subpaths:

• ✅ brk-multihub://contoso.com
• ✅ brk-multihub://localhost:3000 (for dev)
• ❌ brk-multihub://contoso.com/taskpane

This URI is you telling the Microsoft identity platform: “I consent to having my auth brokered by trusted Microsoft 365 hosts.” The multihub part means it’s not just Outlook, the same registration works when your add-in runs brokered inside Word, Excel, PowerPoint, or Teams.

One extra note if your add-in also runs in Word/Excel/PowerPoint on the web: those need an additional plain SPA redirect URI pointing at the actual page that requests tokens (your taskpane HTML), because the browser there still uses a standard flow.

The MSAL Part: One Config, Two Worlds

Here’s the neat thing about how NAA lands in code: you don’t write a mobile version and a desktop version. You write one init function and let it fall back.

import {
  createNestablePublicClientApplication,
  PublicClientApplication,
  type IPublicClientApplication,
  type Configuration,
} from "@azure/msal-browser";

let isNAAMode = false;

async function initMsal(): Promise<IPublicClientApplication> {
  const msalConfig: Configuration = {
    auth: {
      authority: "https://login.microsoftonline.com/common",
      clientId: clientId,
      supportsNestedAppAuth: true,
    },
  };

  try {
    const app = await createNestablePublicClientApplication(msalConfig);
    isNAAMode = true;
    return app;
  } catch {
    // NAA unavailable - fall back to standard MSAL
    isNAAMode = false;
    const app = new PublicClientApplication(msalConfig);
    await app.initialize();
    return app;
  }
}

What’s happening here?

1. supportsNestedAppAuth: true flags the config as NAA-capable. Without it, nothing brokers.
2. createNestablePublicClientApplication tries to hook into the host’s broker. Inside Outlook mobile, it succeeds. In a plain browser tab or an older host, it throws.
3. The catch is the desktop path. Same fallback philosophy as the Graph post: don’t ask “am I on mobile?”, try the capability and let the failure route you. One codebase, two auth worlds, zero platform sniffing.
4. Small but important: initialize this lazily, after Office.onReady() has resolved. The broker hookup needs the Office context to actually be there.

Getting a Token: Let the Host Do the Remembering

In classic MSAL you manage accounts yourself: call getAllAccounts(), pick one, pass it to acquireTokenSilent. In NAA mode you don’t have to, the broker owns the accounts. You just give it a hint about who you expect:

function getLoginHint(): string | undefined {
  return Office.context?.mailbox?.userProfile?.emailAddress ?? undefined;
}

async function getToken(scopes: string[]): Promise<string> {
  const app = await getMsalInstance();

  if (isNAAMode) {
    try {
      const result = await app.acquireTokenSilent({
        scopes,
        loginHint: getLoginHint(),
      });
      return result.accessToken;
    } catch {
      // Silent failed - interactive fallback
    }

    // On mobile this doesn't open a browser popup -
    // the host hands off to the Microsoft Authenticator app
    const result = await app.acquireTokenPopup({ scopes });
    return result.accessToken;
  }

  // Non-NAA (desktop/web): the classic dance -
  // getAllAccounts() → acquireTokenSilent(account) → popup on interaction_required
  return getTokenClassic(app, scopes);
}

What’s happening here?

1. The loginHint is just the signed-in mailbox owner’s email, straight from Office.context.mailbox.userProfile. The broker uses it to resolve the right account, which is exactly the account the user is already signed into Outlook with. No account picker, no cache management.
2. acquireTokenSilent with that hint succeeds almost every time, because of course it does, the user is signed in, that’s how they’re reading their email.
3. When interaction is genuinely needed (first consent, revoked session), acquireTokenPopup doesn’t open a popup on mobile despite its name. The host routes it to Microsoft Authenticator, and the user gets a native sign-in experience that actually works on a phone.
4. The non-NAA branch keeps doing what MSAL apps have always done on desktop. Two branches in one function, and the caller just says getToken(scopes) and never knows which world it’s in.

The first time I watched the Authenticator app slide up over Outlook, approve, and slide away with my Graph call succeeding behind it, it felt like cheating. In a good way. 🎉

Gotchas I Hit Along the Way

• The redirect URI must be SPA type. Adding brk-multihub://... under “Web” or “Mobile and desktop applications” in the app registration silently doesn’t work. It goes under Single-page application, even though nothing about it looks like a page.
• Origin only. brk-multihub://contoso.com/taskpane fails validation. Trim it to the origin.
• MSAL.js v3+. createNestablePublicClientApplication doesn’t exist in v2. Check your @azure/msal-browser version before you spend an hour on confusing import errors.
• No B2C. NAA supports Microsoft accounts and Entra ID work/school accounts. If you’re on Azure AD B2C, this door is closed.

Wrapping Up

That’s the trilogy done. Three posts, one theme: on mobile you don’t get to demand things, you get to ask and adapt.

• The manifest post got us in the door: declare a low requirement floor so mobile shows the add-in at all.
• The Graph fallback post got us the bytes: when the Office.js API isn’t there, fetch the same email from Graph.
• This post got us the token: when there’s no browser to pop, let Outlook broker the auth and Authenticator handle the interaction.

Same shape every time: try the capability, catch the failure, take the other road. Mobile support isn’t one big feature, it’s a stack of small fallbacks that each pretend nothing happened.

The add-in was gone.

Not broken. Not throwing errors. Just… not there. No button, no task pane, nothing. Outlook mobile acted like my add-in didn’t exist.

The Mistake That Feels Like the Right Thing

Here’s the trap. My add-in uses getAsFileAsync() to grab the full email as a file before uploading it to SharePoint. That API lives in the Mailbox 1.14 requirement set. So the obvious, honest, “do the right thing” move is to declare that in the manifest:

<Requirements>
  <Sets>
    <Set Name="Mailbox" MinVersion="1.14" />
  </Sets>
</Requirements>

Makes sense, right? The manifest should declare what the code needs. That’s what a manifest is for.

Wrong.

Outlook reads that MinVersion and treats it as a door policy: “You need Mailbox 1.14 to see this add-in at all.” Outlook on iOS and Android supports Mailbox 1.5 (plus a handful of newer APIs cherry-picked on top). 1.5 is less than 1.14, so mobile doesn’t fail gracefully, it doesn’t show a warning, it just never lets your add-in through the door. That’s why my add-in vanished on my phone.

The manifest version isn’t describing your code. It’s deciding who gets to see your add-in.

The Fix: Degrade the Manifest, Upgrade at Runtime

The fix felt dirty the first time I did it: I “degraded” the manifest down to Mailbox 1.5, even though my code is full of 1.13 and 1.14 APIs.

This is what my add-in actually ships with:

<Requirements>
  <Sets>
    <Set Name="Mailbox" MinVersion="1.5" />
  </Sets>
</Requirements>

And the same low floor inside VersionOverrides:

<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
  <Requirements>
    <bt:Sets DefaultMinVersion="1.5">
      <bt:Set Name="Mailbox"/>
    </bt:Sets>
  </Requirements>
  ...
</VersionOverrides>

Why 1.5? Because that’s what the minimum viable version of my add-in needs: open a task pane, read the current message. Everything above that is a bonus feature, and bonus features shouldn’t decide whether the add-in exists.

One more thing mobile needs, and this one is easy to miss: mobile only renders what you explicitly declare in a MobileFormFactor. Desktop extension points don’t carry over.

<MobileFormFactor>
  <ExtensionPoint xsi:type="MobileMessageReadCommandSurface">
    <Group id="mobileReadGroup">
      <Label resid="groupLabel" />
      <Control xsi:type="MobileButton" id="mobileReadOpenPaneButton">
        <Label resid="taskPaneButtonLabel" />
        <Icon xsi:type="bt:MobileIconList">
          <bt:Image size="25" scale="1" resid="icon25" />
          <!-- ...more sizes and scales... -->
        </Icon>
        <Action xsi:type="ShowTaskpane">
          <SourceLocation resid="messageReadTaskPaneUrl" />
        </Action>
      </Control>
    </Group>
  </ExtensionPoint>
</MobileFormFactor>

Low floor + MobileFormFactor, and suddenly the add-in shows up on my phone. 🎉

Now Your Code Has to Keep the Promise

Here’s the deal you just made: the manifest promises Outlook almost nothing, so your code can’t assume anything. Every API newer than your floor needs a runtime check before you touch it.

Office.js has exactly the tool for this: isSetSupported(). I keep all of mine in one file, platformDetection.ts:

export function isMobilePlatform(): boolean {
  if (typeof Office === 'undefined' || !Office.context?.diagnostics?.platform) {
    return false;
  }

  const hostInfo = Office.context.diagnostics.platform;
  return hostInfo === Office.PlatformType.iOS ||
         hostInfo === Office.PlatformType.Android ||
         hostInfo === Office.PlatformType.Universal; // Includes mobile web
}

export function supportsArchive(): boolean {
  if (typeof Office === 'undefined' || !Office.context?.requirements) {
    return false;
  }

  // getAsFileAsync lives in Mailbox 1.14
  return Office.context.requirements.isSetSupported("Mailbox", "1.14");
}

export function supportsMultiSelect(): boolean {
  if (typeof Office === 'undefined' || !Office.context?.requirements) {
    return false;
  }

  return Office.context.requirements.isSetSupported("Mailbox", "1.13");
}

What’s happening here?

1. isMobilePlatform() asks the host directly what platform it’s running on via Office.context.diagnostics.platform. Note that Universal covers mobile web too, that one surprised me.
2. supportsArchive() checks for Mailbox 1.14 before the code anywhere near getAsFileAsync() runs. On mobile this returns false, and the UI adapts instead of crashing.
3. supportsMultiSelect() does the same for multi-select (Mailbox 1.13). Desktop users get “archive 20 emails at once”, mobile users get one at a time, and nobody gets an error.
4. Every function starts with a typeof Office === 'undefined' guard, so the same code doesn’t explode if it runs outside Outlook (looking at you, local dev in a plain browser tab).

Then the components just ask:

if (supportsArchive()) {
  // Full experience: grab the email with getAsFileAsync and upload it
} else {
  // Degraded experience: hide the feature, or take another route
}

The pattern scales nicely too. In my add-in, when getAsFileAsync isn’t available on mobile, I don’t hide the archive button, I fall back to fetching the message through Microsoft Graph instead. I wrote a follow-up post about exactly that: Same Email, Different Source: Falling Back to Microsoft Graph on Outlook Mobile.

The Contract (Write This on a Sticky Note)

Manifest floor = the lowest host you still want to appear in. Requirement sets in code = runtime capability checks, not install-time gates.

The manifest decides where you exist. The code decides what you can do once you’re there. Mixing those two up is how add-ins silently disappear from half your users’ devices.

Gotchas I Hit Along the Way

• Your manifest can quietly use newer sets than it declares. My manifest declares 1.5 but wires up an OnMessageCompose launch event, which needs Mailbox 1.12. That’s fine, hosts simply ignore extension points they don’t understand. But it means the manifest validator won’t save you here; you have to know which parts light up where.
• Mobile only gets what MobileFormFactor explicitly exposes. No MobileFormFactor, no mobile button, even with a perfect 1.5 floor. And as of writing, mobile read mode is basically the only surface you get.
• Test on an actual phone. The desktop “mobile preview” and your imagination will both lie to you. Sideload it, open a real email on a real device, and watch what happens.

Wrapping Up

Declaring MinVersion="1.14" because your code uses a 1.14 API feels correct, and it’s exactly how you make your add-in invisible on mobile. Degrade the manifest to the lowest version your core experience needs, add a MobileFormFactor, and let isSetSupported() sort out the rest at runtime.

It felt like lying to the manifest at first. It’s not, it’s just answering the question the manifest is actually asking: “What’s the least you need to be useful?”