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
- Open a browser and go to entra.microsoft.com.
- Sign in with an account that has administrator permissions.
You will land on the Microsoft Entra admin center home page.
Step 2 of 8
Register the application
- In the left menu, select Identity, then Applications, then App registrations.
- At the top, select New registration.
- In the Name box, type: SaarthiOS - Read Access
- Under Supported account types, select the first option: Accounts in this organizational directory only (Single tenant).
- 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.
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
- In the application's left menu, select API permissions.
- Select Add a permission, then choose Microsoft Graph.
- Choose Application permissions. This matters - do not choose "Delegated permissions".
- In the search box, type Mail.Read, tick Mail.Read, and select Add permissions.
- Select Grant admin consent for [your organization] and confirm.
The status next to Mail.Read should change to a green Granted tick.
Reference: Microsoft Graph permissions reference.
Step 4 of 8
Create the client secret
- In the left menu, select Certificates & secrets.
- On the Client secrets tab, select New client secret.
- In Description, type: SaarthiOS - Read Access
- 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.
- 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.
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.
# ============================================================
# 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.
# ============================================================
# 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).
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.
# ============================================================
# 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:
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.