{% extends "documentation/base.html" %} {% block doc_content %}

Mail Import Setup

Configure Microsoft Graph API integration to automatically retrieve backup report emails from an Exchange Online mailbox.

Overview

BackupChecks uses the Microsoft Graph API to retrieve emails from an Exchange Online (Microsoft 365) mailbox. This allows the system to automatically import backup reports sent to a dedicated mailbox.

The mail import process involves:

💡 Why Microsoft Graph?
BackupChecks uses Microsoft Graph API instead of traditional IMAP/POP3 because it provides better security (OAuth2), reliability, and integration with Microsoft 365 environments. Most organizations already use Microsoft 365 for email, making this the most convenient option.

Prerequisites

Before configuring mail import in BackupChecks, you need:

  1. Microsoft 365 subscription with Exchange Online
  2. Dedicated mailbox for receiving backup reports (e.g., backupreports@yourdomain.com)
  3. Azure AD application registration with Mail.Read and Mail.ReadWrite permissions
  4. Admin access to BackupChecks to configure settings

Step 1: Create Azure AD App Registration

To allow BackupChecks to access your mailbox, you must create an Azure AD app registration and grant it the necessary permissions.

1.1 Register the Application

  1. Sign in to the Azure Portal
  2. Navigate to Azure Active Directory → App registrations
  3. Click New registration
  4. Enter a name (e.g., "BackupChecks Mail Importer")
  5. Select Accounts in this organizational directory only
  6. Leave Redirect URI blank
  7. Click Register

After registration, note the following values from the Overview page:

1.2 Create a Client Secret

  1. In your app registration, go to Certificates & secrets
  2. Click New client secret
  3. Enter a description (e.g., "BackupChecks access")
  4. Select an expiration period (recommended: 24 months)
  5. Click Add
  6. Important: Copy the secret Value immediately - you cannot view it again later
⚠️ Secret Expiration:
Client secrets expire after the selected period. Set a calendar reminder to renew the secret before expiration, or mail import will stop working. When renewing, create a new secret, update BackupChecks settings, then delete the old secret.

1.3 Grant API Permissions (Start with Read-Only)

BackupChecks requires application permissions (not delegated) to access the mailbox. Start with read-only access for initial testing:

  1. In your app registration, go to API permissions
  2. Remove any default Microsoft Graph permissions that were added automatically
  3. Click Add a permission
  4. Select Microsoft Graph
  5. Select Application permissions (not Delegated)
  6. Search for and add: Mail.Read - Read mail in all mailboxes
  7. Click Add permissions
  8. Important: Click Grant admin consent for [your organization]
  9. Confirm the consent
⚠️ Tenant-Wide Access:
At this stage, the app has permission to read all mailboxes in your tenant. This is a security risk. Follow Step 1.4 (recommended) to restrict access to only the backup mailbox.

1.4 Restrict Access to One Mailbox (Optional but Recommended)

To follow the principle of least privilege, restrict the application to access only the backup mailbox instead of all mailboxes in your tenant.

💡 Security Best Practice:
This step is highly recommended for production environments. It ensures that even if the client secret is compromised, the attacker can only access the backup mailbox, not personal or sensitive mailboxes.

Prerequisites

Restrict via Application Access Policy

  1. Open PowerShell and connect to Exchange Online: 
    Connect-ExchangeOnline -UserPrincipalName admin@yourdomain.com
  2. Create an Application Access Policy to restrict the app to one mailbox: 
    New-ApplicationAccessPolicy `
  -AppId "<CLIENT_ID>" `
  -PolicyScopeGroupId "backupreports@yourdomain.com" `
  -AccessRight RestrictAccess `
  -Description "Allow Graph app to access only the backup mailbox"
  3. Test the policy to verify it's working: 
    Test-ApplicationAccessPolicy `
  -Identity backupreports@yourdomain.com `
  -AppId "<CLIENT_ID>"
  4. Expected result: AccessCheckResult : Granted
  5. Test with a different mailbox to confirm access is denied: 
    Test-ApplicationAccessPolicy `
  -Identity someuser@yourdomain.com `
  -AppId "<CLIENT_ID>"
  6. Expected result: AccessCheckResult : Denied
💡 How It Works:
The Application Access Policy restricts the app to access only the mailbox specified in PolicyScopeGroupId. Even though the app has tenant-wide Mail.Read permissions, Exchange Online enforces the policy and blocks access to other mailboxes.

1.5 Add Write Permissions (After Testing)

Once you've tested read-only access and confirmed it works correctly, add write permissions to allow BackupChecks to move processed emails.

  1. Go back to your app in Azure AD → API permissions
  2. Click Add a permission
  3. Select Microsoft Graph → Application permissions
  4. Add: Mail.ReadWrite - Read and write mail in all mailboxes
  5. Click Add permissions
  6. Important: Click Grant admin consent for [your organization] again
💡 Why ReadWrite?
The Mail.ReadWrite permission is required to move processed emails from the incoming folder to the processed folder. If you only grant Mail.Read, BackupChecks can import emails but cannot move them after processing. They will remain in the incoming folder.

Note: If you configured the Application Access Policy in Step 1.4, the write restriction still applies - the app can only write to the backup mailbox, not other mailboxes.

Step 2: Configure Mail Settings in BackupChecks

After creating the Azure AD app registration, configure BackupChecks to use it:

  1. Log in to BackupChecks as an Admin
  2. Navigate to Settings → General tab
  3. Scroll to the Mail (Microsoft Graph) section

2.1 Enter Graph Credentials

Fill in the following fields with values from your Azure AD app registration:

Field Description Example
Tenant ID Azure AD Directory (tenant) ID 12345678-1234-1234-1234-123456789abc
Client ID Azure AD Application (client) ID 87654321-4321-4321-4321-abcdef123456
Client secret The secret value you copied in Step 1.2 abc123...xyz789
Mailbox address Email address of the mailbox to import from backupreports@yourdomain.com
💡 Security Note:
The client secret field shows ******** (stored) when a secret is already saved. Leave this field empty to keep the existing secret, or enter a new secret to replace it.
⚠️ Important - Save Before Folder Configuration:
You must save the credentials first (click "Save settings" at the bottom) and refresh the page before you can configure folders in Step 2.2. The folder browser requires valid credentials to connect to your mailbox and retrieve the folder list.

2.2 Configure Mail Folders

BackupChecks uses two folders in the mailbox:

Folder Purpose Example Path
Incoming folder Where backup reports arrive and are fetched from Inbox or Inbox/Backup Reports
Processed folder Where emails are moved after processing Archive or Inbox/Processed

To configure folders:

  1. Prerequisites: Ensure you've saved the credentials in Step 2.1 and refreshed the page
  2. Click the Browse... button next to the Incoming folder field
  3. A folder browser popup will open and automatically load your mailbox folder structure
  4. Click on the folder where backup reports arrive (e.g., Inbox)
  5. Click Select to confirm your choice
  6. The folder path will be automatically filled in the field (e.g., Inbox or Inbox/Backup Reports)
  7. Repeat the same process for the Processed folder field
💡 Folder Browser:
The folder browser automatically loads all available folders from your mailbox. You don't need to manually type folder paths - simply click on the folder you want to use. The correct path format (e.g., Inbox/Backup Reports) is automatically generated.
📝 Future Improvement:
The current UI requires clicking the same "Save settings" button twice: once to save credentials (which enables folder browsing), and again to save folder paths. This is not immediately obvious to users. A UI improvement is planned to make this workflow clearer - possibly splitting it into separate sections with distinct save buttons, or providing visual feedback about which step you're on.

2.3 Save Settings (Again)

After configuring the folder paths:

  1. Click the Save settings button at the bottom of the page again
  2. BackupChecks will validate the complete configuration (credentials + folders)
  3. If successful, you'll see a confirmation message
  4. If there's an error, verify:
⚠️ Same Button, Two Steps:
There is only one "Save settings" button on this page. You must click it twice: first after entering credentials (Step 2.1) to enable folder browsing, then again after selecting folders (Step 2.3) to save the complete configuration. This workflow will be improved in a future version to make it clearer.

Step 3: Test the Configuration

After saving settings, verify that mail import is working:

  1. Send a test backup report email to your configured mailbox address
  2. Wait a few minutes for the scheduled import to run (or trigger a manual import - see below)
  3. Navigate to Inbox in BackupChecks
  4. Verify that the test email appears in the inbox

Manual Import

To manually trigger a mail import without waiting for the scheduled task:

  1. Navigate to Settings → Imports tab
  2. Click the Import now button in the "Mail import" section
  3. BackupChecks will immediately fetch new emails from the incoming folder
  4. Check the Inbox page to see imported emails
💡 Import Schedule:
By default, BackupChecks automatically imports new emails every 15 minutes. Manual import is useful for testing or when you need immediate import of a new email.

Troubleshooting

Authentication Errors

If you see "Failed to obtain access token" errors:

Folder Not Found Errors

If folder configuration fails:

No Emails Imported

If manual import succeeds but no emails appear:

Advanced Configuration

Email Retention

BackupChecks stores email content in the database but can also retain the original .eml file for a specified period:

This setting is configured in Settings → Imports tab.

Multiple Mailboxes

BackupChecks currently supports importing from one mailbox at a time. If you need to monitor multiple mailboxes:

Security Best Practices

Next Steps

{% endblock %}