SaarthiOS Secure mailbox access - setup wizard for your Microsoft 365 administrator

Before you start

What we are asking for, and what it allows

We are requesting read-only access to the dedicated mailbox you created for us, so our system can automatically download the documents and reports sent to it. Everything below follows Microsoft's recommended method, with links to their official instructions at each stage.

The integration will be able to

  • Read the emails in the dedicated mailbox
  • Read and download their attachments

It will not be able to

  • Send, reply to, delete, or modify any email
  • Access Teams, SharePoint, OneDrive, or any files
  • Access any Microsoft 365 administrator settings

The permission requested is Mail.Read, which cannot send, delete, or change anything. By default it would allow reading other mailboxes in your organisation too, which is why we recommend the optional restriction in step 6: it limits the application to only the mailboxes you list. No mailbox password is stored anywhere, and the method works with multi-factor authentication enabled.

Why isn't the mailbox password enough?

Microsoft has retired password-only sign-in for automated mailbox access, and it is already disabled on your Microsoft 365 tenant. The recommended approach instead approves a specific application, so access can be centrally managed, audited, and limited to a single mailbox without sharing user credentials.

Terms you will see

  • Microsoft Entra ID - the part of Microsoft 365 that manages sign-ins and permissions (formerly Azure Active Directory).
  • App registration - telling Microsoft "this specific program is approved." It produces two ID numbers.
  • Directory (tenant) ID - an ID number for your organisation.
  • Application (client) ID - an ID number for the approved program.
  • Client secret - a password for the program (not for the mailbox), generated by Microsoft.
  • Admin consent - an administrator's one-time approval of the program's read permission.

At the end you will send us four things: the tenant ID, the client ID, the client secret, and the mailbox address. The final step is a checklist of where each one came from.

Step 1 of 8

Sign in to the admin center

  1. Open a browser and go to entra.microsoft.com.
  2. Sign in with an account that has administrator permissions.

You will land on the Microsoft Entra admin center home page.

Microsoft Entra admin center home page
The Entra admin center after signing in.

Step 2 of 8

Register the application

  1. In the left menu, select Identity, then Applications, then App registrations.
  2. At the top, select New registration.
  3. In the Name box, type: SaarthiOS - Read Access
  4. Under Supported account types, select the first option: Accounts in this organizational directory only (Single tenant).
  5. Leave Redirect URI empty and select Register.

You will now see the application's Overview page. Copy the Directory (tenant) ID and the Application (client) ID (each has a small copy icon) and set them aside - these are two of the four items we need. You will also need the client ID again in step 6.

New registration form in Entra
The registration form.
Application overview page showing the two IDs
The Overview page with both IDs.

Microsoft's guide with screenshots: Register an application. If a screen looks slightly different, Microsoft has likely updated the layout - the button names above are what to look for.

Step 3 of 8

Give it permission to read the mailbox

  1. In the application's left menu, select API permissions.
  2. Select Add a permission, then choose Microsoft Graph.
  3. Choose Application permissions. This matters - do not choose "Delegated permissions".
  4. In the search box, type Mail.Read, tick Mail.Read, and select Add permissions.
  5. Select Grant admin consent for [your organization] and confirm.

The status next to Mail.Read should change to a green Granted tick.

Granting admin consent needs an administrator; a regular user cannot approve it. This is expected.
API permissions page with Mail.Read granted
Mail.Read with admin consent granted.

Reference: Microsoft Graph permissions reference.

Step 4 of 8

Create the client secret

  1. In the left menu, select Certificates & secrets.
  2. On the Client secrets tab, select New client secret.
  3. In Description, type: SaarthiOS - Read Access
  4. Under Expires, choose a period allowed by your policy. Microsoft recommends 12 months or less; note the date so it can be renewed before it expires.
  5. Select Add.

A new row appears with a Value column. Copy the Value now and store it safely - Microsoft shows it only once and it cannot be retrieved later.

Copy the Value, not the Secret ID. They sit next to each other and are easy to mix up. Only the Value is used.
Certificates and secrets page showing the Value column
The secret's Value column - copy this one.

Microsoft's guide: Add a client secret.

Step 5 of 8 - optional, recommended

Restrict access to a chosen list of mailboxes

Steps 1-4 are all the integration needs in order to work. This step is optional security hardening we recommend: it limits the Mail.Read permission so the application can read only the mailboxes you choose - no other mailbox in your organisation.

How it works: your chosen mailboxes are placed in a small mail-enabled security group, and the application is restricted to that group. Adding or removing a mailbox later is just a membership change (step 8), with nothing else to redo.

You do not need any prior PowerShell experience, and there is nothing to edit in the script. When you run it, it asks for the Application (client) ID (from step 2) and your mailbox list, shows a summary, and asks you to confirm before changing anything. A browser window then opens for your admin sign-in and MFA. It is safe to run again - it will not create duplicates.

Administrator: Windows PowerShell
# ============================================================
# SaarthiOS - Restrict app access to selected mailboxes
# Interactive version: prompts for App ID and mailboxes.
# ============================================================

# --- 1. Collect the Application (client) ID ---
do {
    $AppId = (Read-Host "Enter the Application (client) ID").Trim()
    $valid = $AppId -match '^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$'
    if (-not $valid) { Write-Host "  That doesn't look like a valid GUID. Try again." -ForegroundColor Red }
} until ($valid)

# --- 2. Collect mailboxes (one per line, blank line to finish) ---
$Mailboxes = @()
Write-Host ""
Write-Host "Enter the mailbox addresses the app may read." -ForegroundColor Cyan
Write-Host "One per line. Press Enter on an empty line when done." -ForegroundColor Cyan
while ($true) {
    $entry = (Read-Host "Mailbox $($Mailboxes.Count + 1)").Trim()
    if ([string]::IsNullOrWhiteSpace($entry)) {
        if ($Mailboxes.Count -eq 0) {
            Write-Host "  At least one mailbox is required." -ForegroundColor Red
            continue
        }
        break
    }
    if ($entry -notmatch '^[^@\s]+@[^@\s]+\.[^@\s]+$') {
        Write-Host "  Not a valid email address - skipped." -ForegroundColor Red
        continue
    }
    if ($Mailboxes -contains $entry) {
        Write-Host "  Already entered - skipped." -ForegroundColor Yellow
        continue
    }
    $Mailboxes += $entry
}

# --- 3. Confirm before doing anything ---
Write-Host ""
Write-Host "App ID   : $AppId"
Write-Host "Mailboxes:"
$Mailboxes | ForEach-Object { Write-Host "  - $_" }
$go = Read-Host "Proceed? (Y/N)"
if ($go -notmatch '^[Yy]') {
    Write-Host "Cancelled - nothing was changed."
    return
}

# --- 4. Fixed settings ---
$Group = "saarthios-email"
$Desc  = "Email Permission for SaarthiOS"

# --- 5. Install + sign in ---
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force -EA SilentlyContinue
Install-PackageProvider -Name NuGet -Scope CurrentUser -Force -EA SilentlyContinue
if (-not (Get-Module -ListAvailable -Name ExchangeOnlineManagement)) {
    Install-Module ExchangeOnlineManagement -Scope CurrentUser -Force -AllowClobber
}
Import-Module ExchangeOnlineManagement

Write-Host "Signing in - a window will open, complete MFA as usual..."
Connect-ExchangeOnline -ShowBanner:$false -EA Stop

# --- 6. Create the group if needed ---
$g = Get-DistributionGroup -Identity $Group -EA SilentlyContinue
if (-not $g) {
    New-DistributionGroup -Name "SaarthiOS Email" -Alias $Group -Type Security | Out-Null
    Start-Sleep -Seconds 15
}

# --- 7. Add mailboxes ---
foreach ($m in $Mailboxes) {
    try {
        Add-DistributionGroupMember -Identity $Group -Member $m -EA Stop
        Write-Host "Added: $m" -ForegroundColor Green
    } catch {
        Write-Host "Skipped ($m): $($_.Exception.Message)" -ForegroundColor Yellow
    }
}

# --- 8. Apply the restriction ---
$all    = Get-ApplicationAccessPolicy -EA SilentlyContinue
$exists = $all | Where-Object { $_.AppId -eq $AppId }
if (-not $exists) {
    $p = @{
        AppId              = $AppId
        PolicyScopeGroupId = $Group
        AccessRight        = "RestrictAccess"
        Description        = $Desc
    }
    New-ApplicationAccessPolicy @p | Out-Null
    Write-Host "DONE - the app can read only the listed mailboxes." -ForegroundColor Green
} else {
    Write-Host "A restriction already exists - no change made." -ForegroundColor Cyan
}

Write-Host "Microsoft can take up to 30 minutes to apply this."
Disconnect-ExchangeOnline -Confirm:$false | Out-Null

Two ways to run it. Easiest: select Copy script, open PowerShell, paste, and press Enter. Or: download the file, open PowerShell in your Downloads folder, and run powershell -ExecutionPolicy Bypass -File .\Setup-SaarthiOS-MailboxAccess.ps1 (Windows marks downloaded scripts as blocked; this runs it for that one session).

After it runs, the application can read only the mailboxes in your list. Microsoft can take up to 30 minutes to apply this everywhere.

Reference: Limit application permissions to specific mailboxes.

Step 6 of 8 - optional

Check the restriction is working

This step changes nothing. It only asks Microsoft what the application is allowed to reach, and prints the answer, so you can confirm step 5 took effect.

The script asks for the Application (client) ID, one mailbox from your allowed list, and any other mailbox at your company that should not be reachable. The first should come back allowed, the second blocked.

Administrator: Windows PowerShell
# ============================================================
# SaarthiOS - Verify the mailbox restriction
# Interactive version: prompts for App ID, an allowed mailbox,
# and any other mailbox (to confirm it is blocked).
# Read-only - changes nothing.
# ============================================================

# --- 1. Collect inputs ---
do {
    $AppId = (Read-Host "Enter the Application (client) ID").Trim()
    $valid = $AppId -match '^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$'
    if (-not $valid) { Write-Host "  That doesn't look like a valid GUID. Try again." -ForegroundColor Red }
} until ($valid)

$emailPattern = '^[^@\s]+@[^@\s]+\.[^@\s]+$'

do {
    $Allowed = (Read-Host "Enter a mailbox that SHOULD be allowed (one from your list)").Trim()
    $ok = $Allowed -match $emailPattern
    if (-not $ok) { Write-Host "  Not a valid email address. Try again." -ForegroundColor Red }
} until ($ok)

do {
    $Other = (Read-Host "Enter any OTHER mailbox (should be blocked)").Trim()
    $ok = $Other -match $emailPattern
    if (-not $ok) { Write-Host "  Not a valid email address. Try again." -ForegroundColor Red }
    elseif ($Other -eq $Allowed) {
        Write-Host "  Must be different from the allowed mailbox. Try again." -ForegroundColor Red
        $ok = $false
    }
} until ($ok)

# --- 2. Sign in ---
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force -EA SilentlyContinue
Import-Module ExchangeOnlineManagement
Write-Host ""
Write-Host "Signing in - a window will open, complete MFA as usual..."
Connect-ExchangeOnline -ShowBanner:$false -EA Stop

# --- 3. Test both mailboxes ---
$a = Test-ApplicationAccessPolicy -Identity $Allowed -AppId $AppId -EA SilentlyContinue
$b = Test-ApplicationAccessPolicy -Identity $Other   -AppId $AppId -EA SilentlyContinue

Write-Host ""
if (-not $a) {
    Write-Host "$Allowed : not checked - blank or no such mailbox here" -ForegroundColor Yellow
} elseif ($a.AccessCheckResult -eq "Granted") {
    Write-Host "$Allowed : ALLOWED as expected" -ForegroundColor Green
} else {
    Write-Host "$Allowed : NOT allowed - unexpected, please contact us" -ForegroundColor Red
}

if (-not $b) {
    Write-Host "$Other : not checked - blank or no such mailbox here" -ForegroundColor Yellow
} elseif ($b.AccessCheckResult -eq "Denied") {
    Write-Host "$Other : BLOCKED as expected - the restriction works" -ForegroundColor Green
} else {
    Write-Host "$Other : not blocked yet - wait a few minutes, run again" -ForegroundColor Yellow
}

Disconnect-ExchangeOnline -Confirm:$false | Out-Null

Two ways to run it. Easiest: select Copy script, open PowerShell, paste, and press Enter. Or: download the file, open PowerShell in your Downloads folder, and run powershell -ExecutionPolicy Bypass -File .\Verify-SaarthiOS-MailboxAccess.ps1 (Windows marks downloaded scripts as blocked; this runs it for that one session).

If the second mailbox is not blocked yet, that is normal straight after step 5 - Microsoft can take up to 30 minutes to apply the change everywhere. Wait a few minutes and run it again.

Step 7 of 8 - when needed later

Add or remove mailboxes from the list

If you later want to change which mailboxes the application can read, you do not need to repeat step 5. This script adjusts the group membership and the restriction applies to the updated list automatically.

It asks which mailboxes to add and which to remove - press Enter on an empty line to skip either list - then shows the changes and asks you to confirm. It prints the full allowed list at the end so you can verify.

Administrator: Windows PowerShell
# ============================================================
# SaarthiOS - Add / remove allowed mailboxes
# Interactive version: prompts for mailboxes to add and to
# remove, then shows the final list.
# Both sections are optional - press Enter to skip either.
# ============================================================

$Group        = "saarthios-email"
$emailPattern = '^[^@\s]+@[^@\s]+\.[^@\s]+$'

function Read-MailboxList {
    param([string]$Prompt)
    $list = @()
    Write-Host ""
    Write-Host $Prompt -ForegroundColor Cyan
    Write-Host "One per line. Press Enter on an empty line to finish (or skip)." -ForegroundColor Cyan
    while ($true) {
        $entry = (Read-Host "  Mailbox $($list.Count + 1)").Trim()
        if ([string]::IsNullOrWhiteSpace($entry)) { break }
        if ($entry -notmatch $emailPattern) {
            Write-Host "  Not a valid email address - skipped." -ForegroundColor Red
            continue
        }
        if ($list -contains $entry) {
            Write-Host "  Already entered - skipped." -ForegroundColor Yellow
            continue
        }
        $list += $entry
    }
    return ,$list
}

# --- 1. Collect inputs ---
$Add    = Read-MailboxList "Mailboxes to ADD (gain access):"
$Remove = Read-MailboxList "Mailboxes to REMOVE (lose access):"

$overlap = $Add | Where-Object { $Remove -contains $_ }
if ($overlap) {
    Write-Host ""
    Write-Host "These appear in BOTH lists and will be ignored:" -ForegroundColor Red
    $overlap | ForEach-Object { Write-Host "  - $_" }
    $Add    = $Add    | Where-Object { $overlap -notcontains $_ }
    $Remove = $Remove | Where-Object { $overlap -notcontains $_ }
}

if ($Add.Count -eq 0 -and $Remove.Count -eq 0) {
    Write-Host "Nothing to do - no mailboxes entered." -ForegroundColor Yellow
    return
}

# --- 2. Confirm ---
Write-Host ""
if ($Add.Count -gt 0) {
    Write-Host "Will ADD:"
    $Add | ForEach-Object { Write-Host "  + $_" -ForegroundColor Green }
}
if ($Remove.Count -gt 0) {
    Write-Host "Will REMOVE:"
    $Remove | ForEach-Object { Write-Host "  - $_" -ForegroundColor Red }
}
$go = Read-Host "Proceed? (Y/N)"
if ($go -notmatch '^[Yy]') {
    Write-Host "Cancelled - nothing was changed."
    return
}

# --- 3. Sign in ---
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force -EA SilentlyContinue
Import-Module ExchangeOnlineManagement
Write-Host "Signing in - a window will open, complete MFA as usual..."
Connect-ExchangeOnline -ShowBanner:$false -EA Stop

# --- 4. Apply changes ---
foreach ($m in $Add) {
    try {
        Add-DistributionGroupMember -Identity $Group -Member $m -EA Stop
        Write-Host "Added: $m" -ForegroundColor Green
    } catch {
        Write-Host "Skipped ($m): $($_.Exception.Message)" -ForegroundColor Yellow
    }
}
foreach ($m in $Remove) {
    try {
        Remove-DistributionGroupMember -Identity $Group -Member $m -Confirm:$false -EA Stop
        Write-Host "Removed: $m" -ForegroundColor Green
    } catch {
        Write-Host "Skipped ($m): $($_.Exception.Message)" -ForegroundColor Yellow
    }
}

# --- 5. Show final state ---
Write-Host ""
Write-Host "Current allowed mailboxes:" -ForegroundColor Cyan
$members = Get-DistributionGroupMember -Identity $Group -EA SilentlyContinue
if ($members) {
    $members | Select-Object -ExpandProperty PrimarySmtpAddress | ForEach-Object { Write-Host "  $_" }
} else {
    Write-Host "  (none - the app currently has access to no mailboxes)" -ForegroundColor Yellow
}

Write-Host "Microsoft can take up to 30 minutes to apply changes everywhere."
Disconnect-ExchangeOnline -Confirm:$false | Out-Null

Two ways to run it. Easiest: select Copy script, open PowerShell, paste, and press Enter. Or: download the file, open PowerShell in your Downloads folder, and run powershell -ExecutionPolicy Bypass -File .\Update-SaarthiOS-MailboxAccess.ps1 (Windows marks downloaded scripts as blocked; this runs it for that one session).

Step 8 of 8

Send us four things

That completes the setup. Please send these four items to your SaarthiOS contact:

Please send the client secret through a secure channel - a password manager or an encrypted message, not plain email. The original mailbox password is not used by this method.

Questions or help

If any step is unclear, we are happy to answer questions or clarify anything for your team. This is Microsoft's standard, recommended way to give a trusted application read-only access to a single mailbox.