Mailboxes

Complete guide to setting up and configuring mailbox connections for automated email processing.

Introduction
Microsoft Graph (Exchange Online) setup
IMAP4 configuration
General mailbox settings
Best practices
Troubleshooting

Introduction

Mailbox configurations define how the system connects to and processes emails from your mailboxes. You can configure mailboxes using two provider types:

Microsoft Graph — For Microsoft 365 / Exchange Online mailboxes (recommended)
IMAP4 — For standard IMAP mailboxes (Gmail, Outlook.com, custom IMAP servers, etc.)

Each mailbox configuration includes connection settings, polling intervals, security options, and post-processing policies. The system automatically polls configured mailboxes at the specified interval and processes unread emails according to your Mail rules.

What you can do in the Admin UI

Add mailboxes using Microsoft Graph or IMAP4
Set polling interval — how often unread mail is fetched
Choose default terminal — fallback when a rule does not specify one
Enable or disable mailboxes
Edit credentials and folder settings
Test connection before saving

Microsoft Graph (Exchange Online) setup

Microsoft Graph is the recommended method for connecting to Exchange Online / Microsoft 365 mailboxes. It provides secure, application-level access without requiring individual user credentials.

Azure AD app registration

To use Microsoft Graph, register an application in Azure Active Directory and obtain the following credentials:

Navigate to Azure Portal
- Go to portal.azure.com
- Navigate to Azure Active Directory → App registrations
- Click New registration
Register the application
- Enter a name (e.g. "ConPDS Mailbox Access")
- Select Accounts in this organizational directory only
- Click Register
Get Tenant ID
- On the app Overview page, copy Directory (tenant) ID
- Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Get Client ID
- On the same Overview page, copy Application (client) ID
- Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Create Client Secret
- Navigate to Certificates & secrets
- Click New client secret
- Enter a description (e.g. "Mailbox Access Secret")
- Select expiration (recommended: 24 months)
- Click Add
- Important: Copy the secret Value immediately — it will not be shown again

Security note

Store your Client Secret securely. If you lose it, you must create a new one. The secret value is only displayed once when created.

Required permissions

Your Azure AD application needs the following Microsoft Graph API application permissions (not delegated):

In your app registration, go to API permissions → Add a permission → Microsoft Graph → Application permissions
Add:
- Mail.Read
- Mail.ReadWrite (if you need to mark messages as read)
- User.Read.All (if accessing multiple mailboxes)
Click Grant admin consent for [Your Organization] and confirm
Verify all permissions show Granted for [Your Organization] with a green checkmark

Permission types

Application permissions allow the app to access mailboxes without a signed-in user — required for automated email processing. Delegated permissions require a user to sign in and are not suitable for this use case.

Exchange Online configuration

After registering your Azure AD application, grant it access to specific mailboxes in Exchange Online using PowerShell.

Prerequisites:

Install the Exchange Online Management PowerShell module
Connect to Exchange Online with appropriate admin credentials
Have the Application (Client) ID from your Azure AD app registration

Grant mailbox access:

# Grant full access to a mailbox
Add-MailboxPermission `
  -Identity "mailbox@example.com" `
  -User "your-app-client-id" `
  -AccessRights FullAccess `
  -AutoMapping $false

Parameter	Description
Identity	Email address of the mailbox to access
User	Azure AD application Client ID (not the app name)
AccessRights	`FullAccess` allows reading and managing messages
AutoMapping	Set to `$false` to prevent the mailbox appearing in Outlook

Verify mailbox access:

Get-MailboxPermission "mailbox@example.com" |
  Where-Object {$_.User -like "*your-app-client-id*"}

Grant access to multiple mailboxes — repeat Add-MailboxPermission for each mailbox, or use a distribution group for organisation:

Add-DistributionGroupMember `
  -Identity "MailboxAccessGroup" `
  -Member "mailbox1@example.com"

Add-MailboxPermission `
  -Identity "mailbox1@example.com" `
  -User "your-app-client-id" `
  -AccessRights FullAccess `
  -AutoMapping $false

Application access policies (optional but recommended)

Application Access Policies restrict which mailboxes your application can access — especially important when the app has broad permissions.

Create a restriction group:

New-DistributionGroup `
  -Name "AppMailboxAccess" `
  -PrimarySmtpAddress "appmailboxaccess@example.com" `
  -ManagedBy "admin@example.com"

Add-DistributionGroupMember `
  -Identity "AppMailboxAccess" `
  -Member "mailbox1@example.com"

Apply the access policy:

New-ApplicationAccessPolicy `
  -AppId "your-app-client-id" `
  -PolicyScopeGroupId "AppMailboxAccess" `
  -AccessRight RestrictAccess

Verify:

Get-ApplicationAccessPolicy | Where-Object {$_.AppId -eq "your-app-client-id"}

Policy behaviour

With RestrictAccess, your application can only access mailboxes in the specified group. All other mailboxes are denied, even if individual permissions were granted.

Configuration in ConPDS Checker:

Select Provider Type: Microsoft Graph
Enter Tenant ID, Client ID, and Client Secret
Enter the Mailbox Email address to access
Click Test connection to verify

IMAP4 configuration

IMAP4 is a standard email protocol supported by most providers. Use IMAP when connecting to non-Microsoft mailboxes or when Microsoft Graph is not available.

Basic IMAP configuration

Field	Description
Host	IMAP server hostname (e.g. `imap.gmail.com`, `outlook.office365.com`)
Port	Typically `993` (SSL), `143` (STARTTLS)
Username	Email address or IMAP username
Password	Email password or app-specific password
SSL/TLS	Enable SSL for port 993 (recommended)

Common IMAP providers

Gmail

Host: imap.gmail.com
Port: 993
SSL: Enabled
Requires an App Password (not your regular Gmail password). Enable 2-Step Verification and generate an app password in Google Account settings.

Outlook.com / Hotmail

Host: outlook.office365.com
Port: 993
SSL: Enabled
May require enabling IMAP in account settings. For Microsoft 365, prefer Microsoft Graph.

Custom IMAP server

Contact your email administrator for host, port, and encryption settings.

Security settings

Use SSL — Encrypts the connection (port 993, recommended)
Use STARTTLS — Upgrades port 143 to TLS
Allow Insecure — Unencrypted connections (testing only)
Host Allowlist / Blocklist — Restrict which IMAP hosts may be used

Security warning

Never use Allow Insecure in production. Always use SSL (port 993) or STARTTLS (port 143).

Configuration steps

Select Provider Type: IMAP4
Enter IMAP Host and Port
Enter Username and Password
Enable Use SSL (993) or Use STARTTLS (143)
(Optional) Configure Host Allowlist
Click Test connection

General mailbox settings

These settings apply to all mailbox types.

Basic settings

Setting	Description
Name	Descriptive label (e.g. "Operations Mailbox")
Folder	Folder to monitor (default: `INBOX`)
Polling interval	Minutes between checks (recommended: 5 for active mailboxes)
Active	Enable or disable polling

Limits

Setting	Description
Max messages per poll	Cap per polling cycle (default: 50)
Max attachments per message	Cap per email (default: 20)
Max attachment size	Bytes per attachment (optional; e.g. `10485760` = 10 MB)

Security

Setting	Description
Sender allowlist	Only process email from listed addresses or domains (e.g. `@example.com`)
Require secret token	Email must include a token in subject or body

Post-processing policy

Define what happens to emails after processing:

{
  "on_success": "mark_read",
  "on_failure": "keep_unread",
  "move_to_folder": "Processed"
}

Field	Options
on_success	`mark_read`, `delete`, `no_action`
on_failure	Same as on_success
move_to_folder	Optional folder name after processing

Best practices

Use Microsoft Graph when possible for Microsoft 365 mailboxes
Test connections before saving
Use Application Access Policies to restrict Graph app access
Set appropriate polling intervals — 5 minutes is usually sufficient
Use sender allowlists on public-facing mailboxes
Monitor Processing state regularly
Use descriptive mailbox names
Configure limits to prevent overload
Rotate Graph client secrets before expiry
Always use SSL/TLS for IMAP in production

Troubleshooting

Microsoft Graph: "Invalid credentials" or "Authentication failed"

Verify Tenant ID, Client ID, and Client Secret (no extra spaces)
Check the Client Secret has not expired
Ensure API permissions are granted with admin consent
Verify the mailbox email address
Check mailbox permissions in Exchange Online

Microsoft Graph: "Access denied" or "Forbidden"

Verify Mail.Read or Mail.ReadWrite permissions
Confirm admin consent was provided
Verify Add-MailboxPermission was run
If using Application Access Policy, ensure the mailbox is in the allowed group

IMAP: "Connection failed" or "Authentication failed"

Verify host, port, username, and password
For Gmail, use an App Password
Ensure IMAP is enabled in account settings
Verify SSL/TLS settings match the server
Check firewall rules for outbound IMAP

IMAP: "Host not allowlisted" or "Host blocklisted"

Add the IMAP host to the allowlist or remove from blocklist
Check for typos (hostnames are case-sensitive)

Emails not being processed

Verify the mailbox is Active
Check polling interval — emails are only fetched on schedule
Review Processing state
Check sender allowlist
Verify Mail rules are configured and active

Connection test succeeds but polling fails

Check for rate limiting from the email provider
Review error logs in Processing state
Verify credentials have not changed
Check for a poll lock (use Clear poll lock if needed)

Table of contents​

Introduction​

What you can do in the Admin UI​

Microsoft Graph (Exchange Online) setup​

Azure AD app registration​

Required permissions​

Exchange Online configuration​

Application access policies (optional but recommended)​

IMAP4 configuration​

Basic IMAP configuration​

Common IMAP providers​

Security settings​

Configuration steps​

General mailbox settings​

Basic settings​

Limits​

Security​

Post-processing policy​

Best practices​

Troubleshooting​

Microsoft Graph: "Invalid credentials" or "Authentication failed"​

Microsoft Graph: "Access denied" or "Forbidden"​

IMAP: "Connection failed" or "Authentication failed"​

IMAP: "Host not allowlisted" or "Host blocklisted"​

Emails not being processed​

Connection test succeeds but polling fails​

Table of contents