Admin Guide: Set up Bundul's Microsoft/Outlook Email Integration

Audience: whoever administers Bundul's Microsoft/Azure account. Goal: a company-owned Microsoft directory under bundul.io, a registered app that can read users' Outlook / Microsoft 365 / Outlook.com inboxes (read-only), and the publisher verification needed to go live. Cost: $0 (see notes). Time: ~45 min of work + waiting on domain DNS and partner verification.

There are three parts:

• Part A — create the organizational account (@bundul.io directory + admin).
• Part B — register and configure the app.
• Part C — publisher verification (the go-live gate).

Migration note: if an app was already registered in a personal Microsoft account during testing, it must be re-registered in this new company tenant (registrations are tenant-bound). You'll get a new Client ID + secret and hand those to engineering, then delete the old personal-tenant app.

---

Cost implication

Everything required for this integration is free. There is no per-user, per-API-call, or per-mailbox charge for reading inboxes via Microsoft Graph.

Item	Required?	Cost
Microsoft Entra ID directory (the tenant)	Yes	$0 — Entra ID Free tier
App registration	Yes	$0 — free, even after any Azure trial ends
Custom domain bundul.io (identity verification)	Yes	$0 — DNS TXT record only
Admin identity to own/manage the app	Yes	$0 — an Entra ID Free user (no mailbox, no license)
Microsoft Graph Mail.Read API calls	Yes	$0 — Graph is free; subject only to throttling limits
Microsoft Partner account (for publisher verification)	Yes (go-live)	$0 — free to enroll
Publisher verification	Yes (go-live)	$0
Microsoft 365 mailbox license for @bundul.io	No	~$6+/user/mo — not needed; only if you want the admin to have a real Outlook mailbox
Azure paid resources (compute, storage, etc.)	No	N/A — none used by this integration

Bottom line: $0 to build and go live. The only way this costs money is if someone separately decides to buy a Microsoft 365 mailbox for the admin account — which this integration does not require. (An Azure free-account signup may ask for a card for identity verification, but nothing here incurs a charge.)

Do we need CASA? — certification breakdown

No. Microsoft has no CASA-equivalent security audit to read user email. This is the biggest difference from Google.

	Google (Gmail)	Microsoft (Outlook)
Annual third-party security audit	CASA Tier 2 — required for restricted scopes like gmail.readonly, renewed yearly, involves a paid assessor	None. No CASA, no annual pentest, no Letter of Assessment
Consent-screen identity verification	Google OAuth app verification	Publisher Verification — required for our multi-tenant Mail.Read app
Optional deeper certification	—	Microsoft 365 Certification — optional; only if listing on AppSource or an enterprise customer demands it

What this means for us:

• We must do Publisher Verification (Part C) — but it is identity verification of Bundul as a company (via a free Microsoft Partner account), not a security assessment. No auditor, no fee, no yearly security re-review. It exists because Microsoft blocks users from consenting to unverified multi-tenant apps that request permissions beyond basic sign-in, and Mail.Read qualifies.
• We do NOT need Microsoft 365 Certification to go live. It's the closest thing to CASA, but it's optional and only relevant if we later publish to Microsoft's marketplace or sell to enterprises that require it.
• Net: the Microsoft go-live compliance bar is lighter and cheaper than Gmail's — one free, one-time company identity verification instead of a recurring paid CASA audit.

---

Part A — Create the organizational account (@bundul.io)

A1. Create a company Entra directory (tenant)

1. Go to https://entra.microsoft.com and sign in with any Microsoft account (a personal one is fine just to bootstrap).
2. Identity → Overview → Manage tenants → Create.
3. Choose Microsoft Entra ID (not "External"/B2C). Fill:
   • Organization name: Bundul
   • Initial domain name: bundul → gives bundul.onmicrosoft.com
   • Country/region: your legal region.
4. Create. This directory is free (Entra ID Free tier).
5. Switch into it: top-right Settings (gear) → Switch directory → Bundul.

A2. Add and verify the bundul.io custom domain

1. In the Bundul tenant: Identity → Settings → Domain names → + Add custom domain.
2. Enter bundul.io → Add domain. Microsoft shows a TXT record.
3. Add that TXT record at your DNS provider (wherever bundul.io DNS is managed).
4. Back in Entra, click Verify (allow a few minutes for DNS to propagate).

⚠️ This does not affect email. You're only adding a TXT record for identity proof — the MX records stay with Google Workspace, so @bundul.io mail keeps flowing through Gmail untouched. ⚠️ A domain can be verified in only one Entra tenant — do this in the tenant you intend to keep.

A3. Create the admin identity

1. Identity → Users → All users → + New user → Create new user.
2. User principal name: e.g. msadmin@bundul.io (now selectable because the domain is verified). Prefer a shared, role-based name, not a personal person's.
3. Set display name and password (store it in your team password manager).
4. Assign a role that can manage apps: Application Administrator (or Cloud Application Administrator), or Global Administrator if this person runs the tenant.
5. Create.

This admin identity needs no mailbox and no paid license — it only administers the app. (A real @bundul.io Outlook mailbox would need a paid Microsoft 365 license, which you do not need here.)

A4. Turn on MFA for the admin (recommended)

Identity → Overview → Properties / Security defaults → enable security defaults, or configure Conditional Access to require MFA for admins.

---

Part B — Register and configure the app

Sign in to https://entra.microsoft.com as the @bundul.io admin, in the Bundul tenant.

B1. New app registration

1. Identity → Applications → App registrations → + New registration.
2. Name: Bundul Mail Parser (this shows on the user consent screen).
3. Supported account types: ⚠️ pick "Accounts in any organizational directory (Any Microsoft Entra ID tenant – Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)." This is mandatory to read consumer Outlook.com and work Microsoft 365 inboxes.
4. Skip the redirect URI for now (Step B3). Click Register.
5. On the Overview page, copy Application (client) ID → give to engineering as MICROSOFT_CLIENT_ID.

B2. Graph permissions (delegated, read-only)

1. API permissions → + Add a permission → Microsoft Graph → Delegated permissions.
2. Add: User.Read, Mail.Read, offline_access.
3. These are user-consentable → no "Grant admin consent" needed for consumer/most work accounts. Mail.Read is read-only; offline_access is what provides the refresh token.

B3. Redirect URI (the app's login redirect)

The Bundul mobile app performs the Microsoft sign-in and sends the backend an auth code. Register the exact redirect URI the app uses:

1. Authentication → + Add a platform → Mobile and desktop applications (or Web, per what the app uses).
2. Enter the redirect URI provided by the mobile engineering team (e.g. an MSAL/custom-scheme URI).
3. Save. Hand this same value to engineering — it must equal MICROSOFT_CALLBACK_URL, or the backend can't redeem the code.

B4. Client secret

1. Certificates & secrets → + New client secret.
2. Description bundul-backend, expiry ≤ 24 months (note the date).
3. Add, then immediately copy the secret Value (the long string — NOT "Secret ID"; shown once) → give to engineering as MICROSOFT_CLIENT_SECRET.
4. Set a calendar reminder ~2 weeks before expiry to rotate it — when it lapses, all Outlook syncing breaks.

B5. Branding

Branding & properties → set logo, Publisher display name, Home page URL, Terms of service URL, Privacy statement URL, and set Publisher domain to bundul.io. (Publisher domain must be a verified domain — Part A2 covers this.)

---

Part C — Publisher Verification (go-live gate)

Without this, Microsoft blocks or warns users trying to consent to a multi-tenant app that requests Mail.Read. It is not a security audit (unlike Google's CASA) — it's a one-time verification of your company's identity.

C1. Create a Microsoft Partner account (free)

1. Go to https://partner.microsoft.com and enroll in the Microsoft AI Cloud Partner Program.
2. Complete business verification. You'll receive a Partner ID (MPN ID). (Business verification can take a few days — start this early.)

C2. Align domains

Ensure the partner account and the app's Publisher domain both correspond to bundul.io (verified in Part A2).

C3. Verify the publisher on the app

1. In the app registration → Branding & properties → Publisher verification → Add MPN ID.
2. Enter the Partner ID and Verify.
3. Success = a blue "verified" badge on the consent screen, the "unverified/not commonly used" warning disappears, and multi-tenant users can consent to Mail.Read.

---

Part D — Hand off to engineering

Deliver these three values (the secret via a password manager / secrets tool, never plain email/chat):

Value	Where it comes from	Env var
Application (client) ID	Part B1 (Overview)	MICROSOFT_CLIENT_ID
Client secret Value	Part B4	MICROSOFT_CLIENT_SECRET
Redirect URI	Part B3 (must match the app's)	MICROSOFT_CALLBACK_URL

---

Go-live checklist

• Company Entra tenant created; bundul.io verified (Part A1–A2)
• @bundul.io admin identity with an app-admin role + MFA (A3–A4)
• App registered as multitenant + personal accounts (B1)
• Delegated User.Read + Mail.Read + offline_access (B2)
• Redirect URI registered and matches MICROSOFT_CALLBACK_URL (B3)
• Client secret created, stored in secrets manager, rotation reminder set (B4)
• Branding set; Publisher domain = bundul.io (B5)
• Publisher verification complete (Partner ID linked) (Part C)
• Old personal-tenant app deleted; engineering updated with new Client ID/secret
• Verified by connecting a real Outlook.com and a Microsoft 365 mailbox through the app