Connecting to IMAP servers

Basic Connectivity

AlertMagic allows you to ingest emailed events via the IMAP protocol. To permit this, you first need to add an "IMAP Server" Connection.

Method 1: Authenticating with Username and Password

This is the standard method for authenticating with an IMAP server using basic authentication.

In the URL field, enter your secure IMAP server in the form imaps://<server>:<port>

Example: imaps://imap.gmail.com:993
You can change the server and port.
You cannot change the protocol, as only secure connections are supported.
Make sure there is no trailing slash.

In the Username field:

Enter your IMAP username.
Usually the account's email address.

In the Password field:

Many providers, including Google, require that you create a dedicated application password.
If you need this for Gmail, click here.

In the Configuration field, you will typically add your AlertMagic Integration JSON (see "AlertMagic Integration" section below). No specific authentication parameters are added to this JSON for this method, as username/password are handled directly by the fields above.

Method 2: Authenticating with OAuth2 (Client Credentials Grant for Microsoft 365/Azure)

AlertMagic supports OAuth2 for IMAP connections specifically using the Client Credentials grant flow. This method is suitable for server-to-server authentication where AlertMagic needs to access a protected resource (reading emails) without a user present, and it requires registering an application in your email provider's identity system (e.g., Azure Active Directory for Microsoft 365).

This Microsoft documentation page provides general information - be sure to follow instructions for the IMAP Client Credentials grant flow. See below for full set-up instructions.

Important Note: The Client Credentials grant flow is primarily supported by Microsoft (Azure Active Directory) for service-to-server communication. Google (Gmail) does not support the Client Credentials grant flow for IMAP connections via their APIs. Therefore, AlertMagic's OAuth2 IMAP capability is currently limited to Microsoft 365/Azure environments.

In the URL field, enter your secure IMAP server in the form imaps://<server>:<port>

Example: imaps://outlook.office365.com:993
You can change the server and port.
You cannot change the protocol, as only secure connections are supported.
Make sure there is no trailing slash.

In the User name field, enter the email address of the mailbox that the service account has permissions to access (e.g., reports@yourcompany.com). This is the identity for which AlertMagic will retrieve mail.
In the Password field, enter the Client Secret obtained from your application registration in Azure Active Directory.

In the Configuration field, enter JSON that includes both the OAuth2 parameters and your AlertMagic Integration (if applicable). For example:

{
  "GrantType":"ClientCredentials",
  "AuthType":"OAuth2",
  "ClientID": "YOUR_CLIENT_ID",
  "Scope":"https://outlook.office365.com/.default",
  "TokenUrl":"https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token",
  "ClientAuthType":"SendClientCredentialsInBody",
  "AlertMagic": {
    "Ingests": [
      {
        "Name": "Knock Knock",
        "Uri": "https://pdl-alertmagic-production.azurewebsites.net/api/notify",
        "Username": "xxx",
        "Password": "yyy",
        "Filter": {
          "From": "^tri.+@zion.com$",
          "Subject": "^alert",
          "Body": "white.+rabbit"
        },
        "Payload": {
          "FromCaptures": [
            "^(?<from>.+)$"
          ],
          "SubjectCaptures": [
            "^alert - (?<subject>.+)$"
          ],
          "BodyCaptures": [
            "Spoon: (?<spoon>[^\n]+)",
            "Skills: (?<skills>[^\n]+)"
          ]
        },
        "CleanUp": {
          "Action": "MoveToFolder",
          "Folder": "AlertMagic Processed",
          "DeleteAfterDays": 30
        }
      }
    ]
  }
}

Explanation of Configuration fields for OAuth2 (Client Credentials):

"GrantType": Must be set to "ClientCredentials".
"AuthType": Must be set to "OAuth2".
"ClientID": This is the Application (client) ID obtained from your application registration in Azure Active Directory.
"Scope": The permissions AlertMagic requires. For Microsoft 365, https://outlook.office365.com/.default is a common scope for reading mail on behalf of the application itself.
"TokenUrl": The OAuth2 token endpoint for your Microsoft 365 tenant. The YOUR_TENANT_ID will be your Azure AD Tenant ID (Directory ID).
"ClientAuthType": Specifies how the client credentials (ClientID and ClientSecret) are sent to the token endpoint. "SendClientCredentialsInBody" means they are sent in the request body.

AlertMagic Integration

AlertMagic can be configured to pick up emails from the IMAP server, parse them, repackage as JSON and send the results to AlertMagic. This is achieved using an "AlertMagic" node in the JSON configuration fields (as seen in the OAuth2 example above, or as the sole content of the Configuration field for Username/Password authentication). This is best illustrated with an example:

Incoming email:

From: trinity@zion.com

Subject: alert - Wake up Neo

Body:

Follow the white rabbit
Spoon: false
Skills: "Kung Fu", "Helicopter Pilot"

Configuration (example illustrating only the AlertMagic node):

{
    "AlertMagic": {
        "Ingests": [
            {
                "Name": "Knock Knock",
                "Uri": "https://pdl-alertmagic-production.azurewebsites.net/api/notify",
                "Username": "xxx",
                "Password": "yyy",
                "Filter": {
                    "From": "^tri.+@zion.com$",
                    "Subject": "^alert",
                    "Body": "white.+rabbit"
                },
                "Payload": {
                    "FromCaptures": [
                        "^(?<from>.+)$"
                    ],
                    "SubjectCaptures": [
                        "^alert - (?<subject>.+)$"
                    ],
                    "BodyCaptures": [
                        "Spoon: (?<spoon>[^\n]+)",
                        "Skills: (?<skills>[^\n]+)"
                    ]
                },
                "CleanUp": {
                    "Action": "MoveToFolder",
                    "Folder": "AlertMagic Processed",
                    "DeleteAfterDays": 30
                }
            }
        ]
    }
}

In this configuration example, incoming emails are only processed if they are from someone whose name starts with "tri", working for "zion.com". Next, the Subject line must start with the word alert and the Body must contain the words "white" and "rabbit" in that order. The text is scanned for the fields "Spoon" and "Skills".

The result would be a new WebHook, injected into AlertMagic's Integration with Id = 123, as follows:

{
"from": "trinity@zion.com",
"subject": "Wake up Neo",
"spoon": "false",
"skills": "\"Kung Fu\", \"Helicopter Pilot\""
}

Note that only string values are supported at present.

Configuring Azure AD for Magic Suite IMAP Access

Overview: This guide explains how to configure your Azure Active Directory tenant to allow Magic Suite (Panoramic Data's SaaS platform) to securely access email from specific mailboxes in your organization using OAuth 2.0 authentication. This eliminates the need for storing passwords and provides fine-grained access control.

Why OAuth for IMAP?

✓ No passwords stored - More secure than basic authentication
✓ Granular control - Restrict access to specific mailboxes only
✓ Auditable - Track when and how Magic Suite accesses your email
✓ Revocable - Disable access instantly without changing passwords
✓ Compliant - Meets modern security standards and compliance requirements

Magic Suite Application Details

Application Name: Magic Suite
Provider: Panoramic Data Limited
Magic Suite Application (Client) ID: eb6992c6-9e08-444d-be7d-17b490f2f3d3
Required Permissions: Office 365 Exchange Online - IMAP.AccessAsApp
Access Scope: Only mailboxes you explicitly grant access to
Authentication Method: OAuth 2.0 Multi-Tenant Application

Prerequisites:

You must be a Global Administrator or Application Administrator in your Azure AD tenant
Your organization must have Microsoft 365 with Exchange Online
PowerShell must be available for Exchange Online configuration

Configuration Steps

Step 1: Consent to Magic Suite Application

What This Does: This step registers the Magic Suite application in your Azure AD tenant and grants it permission to access Exchange Online via IMAP. You maintain complete control over which mailboxes can be accessed.

Initiate Admin Consent
Click the following admin consent URL (you must be logged in as a Global Administrator or Application Administrator):

https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=eb6992c6-9e08-444d-be7d-17b490f2f3d3&scope=https://outlook.office365.com/.default

Or manually construct the URL with your specific tenant:

https://login.microsoftonline.com/{YOUR_TENANT_ID}/v2.0/adminconsent?client_id=eb6992c6-9e08-444d-be7d-17b490f2f3d3&scope=https://outlook.office365.com/.default
Review Permissions
You will see a consent screen showing:
- Application: Magic Suite
- Publisher: Panoramic Data Limited
- Permissions requested:
Grant Admin Consent
Review the permissions carefully

Check the box "Consent on behalf of your organization"

Click "Accept"

You should see a confirmation that permissions have been granted. The Magic Suite service principal is now registered in your tenant.
Verify the Application Registration (Optional)
Go to Azure Portal → Azure Active Directory → Enterprise applications

Search for "Magic Suite" - you should see it listed

Click on it and go to "Permissions" to verify the IMAP.AccessAsApp permission is granted

Step 2: Configure Exchange Online Access Policy

What This Does: This creates a security policy that explicitly defines which mailbox(es) Magic Suite can access. Without this policy, the application cannot access any mailboxes, even with admin consent.

Install Exchange Online Management Module
Open PowerShell as Administrator
# Install the module (one-time setup) Install-Module ExchangeOnlineManagement -Force -AllowClobber # Import the module Import-Module ExchangeOnlineManagement
Connect to Exchange Online # Connect to your Exchange Online environment Connect-ExchangeOnline # You will be prompted to sign in with your admin credentials
Identify the Mailbox to Grant Access
Determine which mailbox(es) Magic Suite needs to access. This is typically a shared mailbox or service account that receives monitoring alerts, tickets, or notifications.
Example mailboxes:
- alerts@yourcompany.com
- monitoring@yourcompany.com
- servicedesk@yourcompany.com
Verify the mailbox exists:
Get-Mailbox your-mailbox@yourcompany.com | Select-Object DisplayName, PrimarySmtpAddress
Ensure IMAP is Enabled for the Mailbox # Check current IMAP status Get-CASMailbox your-mailbox@yourcompany.com | Select-Object ImapEnabled # If IMAP is disabled, enable it: Set-CASMailbox your-mailbox@yourcompany.com -ImapEnabled $true
Create the Application Access Policy
This is the critical security step that restricts Magic Suite to ONLY the mailbox(es) you specify:
# Define the Magic Suite application ID $appId = "eb6992c6-9e08-444d-be7d-17b490f2f3d3" # Define your mailbox $mailbox = "your-mailbox@yourcompany.com" # Create the access policy New-ApplicationAccessPolicy ` -AppId $appId ` -PolicyScopeGroupId $mailbox ` -AccessRight RestrictAccess ` -Description "Allow Magic Suite to access monitoring mailbox via IMAP"
Note: The RestrictAccess right means the application can ONLY access mailboxes listed in the policy. This is the most secure option.
Verify the Configuration # View the policy Get-ApplicationAccessPolicy | Where-Object { $_.AppId -eq $appId } | Format-List # Test that access is granted Test-ApplicationAccessPolicy -Identity $mailbox -AppId $appId
Expected Result:
AccessCheckResult: Granted

If you see "Granted", the configuration is complete and working correctly!
(Optional) Grant Access to Multiple Mailboxes
If Magic Suite needs to access multiple mailboxes, you have two options:

Option A: Create a distribution group containing all mailboxes, then use the group in the policy
# Create a distribution group New-DistributionGroup -Name "MagicSuiteAccessGroup" -Members mailbox1@yourcompany.com,mailbox2@yourcompany.com # Use the group in the policy New-ApplicationAccessPolicy -AppId $appId -PolicyScopeGroupId "MagicSuiteAccessGroup" -AccessRight RestrictAccess
Option B: Create separate policies for each mailbox (simpler but more policies to manage)
# Create individual policies New-ApplicationAccessPolicy -AppId $appId -PolicyScopeGroupId "mailbox1@yourcompany.com" -AccessRight RestrictAccess New-ApplicationAccessPolicy -AppId $appId -PolicyScopeGroupId "mailbox2@yourcompany.com" -AccessRight RestrictAccess

Step 3: Provide Configuration Details to Panoramic Data

What to Share: Once configuration is complete, provide the following information to your Panoramic Data contact to complete the Magic Suite setup:

Information Needed	Where to Find It
Your Tenant ID	Azure Portal → Azure Active Directory → Overview → Tenant ID
Mailbox Email Address(es)	The email address(es) you configured in the access policy
Confirmation of Admin Consent	Confirm that you completed Step 1 successfully

⚠️ Do NOT share:

Passwords for any user accounts
Service principal secrets (not needed - Panoramic Data manages their own application credentials)
Any other sensitive credentials

How Magic Suite Authenticates

Technical Details: Understanding how the authentication works helps ensure your security team is comfortable with the setup.

Magic Suite uses its own Azure AD application and credentials (managed by Panoramic Data) to authenticate
When accessing your tenant, Magic Suite requests an OAuth token from Azure AD using the multi-tenant application flow
Azure AD verifies that:
- Your admin granted consent (Step 1)
- The requested mailbox is in your Application Access Policy (Step 2)
- The request comes from the legitimate Magic Suite application
Only if all checks pass, Azure AD issues a token that allows Magic Suite to connect to your Exchange Online IMAP server
The token is short-lived (typically 1 hour) and must be renewed regularly
All access is logged in your Azure AD sign-in logs and Exchange audit logs

Security & Compliance

Access Control

✓ Magic Suite can ONLY access mailboxes explicitly listed in your Application Access Policy

✓ No passwords are shared or stored by Magic Suite

✓ Access can be revoked instantly by removing the Application Access Policy or withdrawing admin consent

Auditing

View Magic Suite Access in Azure AD Sign-in Logs:

Azure Portal → Azure Active Directory → Sign-in logs → Filter by Application: "Magic Suite"
        

View Exchange Online Mailbox Access:

# PowerShell command to check audit logs

Search-MailboxAuditLog -Identity your-mailbox@yourcompany.com -StartDate (Get-Date).AddDays(-7) -ShowDetails

Revoking Access

Option 1: Remove the Application Access Policy (Recommended)

# List policies

Get-ApplicationAccessPolicy | Where-Object { $_.AppId -eq "eb6992c6-9e08-444d-be7d-17b490f2f3d3" }

# Remove specific policy

Remove-ApplicationAccessPolicy -Identity "policy-identity-from-above"

Option 2: Remove Admin Consent (Nuclear option - affects all mailboxes)

Azure Portal → Azure Active Directory → Enterprise applications → Magic Suite → Permissions → Remove permissions
        

✅ Configuration Checklist

Before Going Live

Admin consent granted for Magic Suite application

Magic Suite appears in Enterprise Applications in Azure Portal

IMAP.AccessAsApp permission is visible and consented

IMAP is enabled for the target mailbox(es)

Application Access Policy created in Exchange Online

Test-ApplicationAccessPolicy returns "Granted"

Tenant ID and mailbox address provided to Panoramic Data

Security team informed and approved the configuration

Frequently Asked Questions

Q: Can Magic Suite access all our mailboxes?

A: No. Magic Suite can ONLY access mailboxes that you explicitly list in the Application Access Policy. The application has no access to any other mailboxes.

Q: What data can Magic Suite access?

A: Magic Suite has read-only IMAP access to the configured mailbox(es). It can read email messages and folder structure, but cannot send email, delete messages, or modify mailbox settings (unless additional permissions are explicitly granted).

Q: How do we know if Magic Suite is accessing our mailbox?

A: All authentication attempts are logged in Azure AD sign-in logs. You can also enable mailbox auditing in Exchange Online to track all access to specific mailboxes.

Q: What happens if we revoke access?

A: Magic Suite will immediately lose the ability to obtain new authentication tokens. Any active connections will fail on the next authentication attempt (within 1 hour). This will cause any Magic Suite features that depend on email access to stop working.

Q: Can we use a regular user mailbox instead of a shared mailbox?

A: Yes, technically. However, shared mailboxes or resource mailboxes are recommended because they don't consume user licenses and are designed for application access.

Q: How long does the client secret last?

A: When creating your client secret, you can set the expiry time. We recommend setting the maximum and configuring that time in the Connection UI in Magic Suite. We can then remind your to rotate the client secret at the appropriate time.

Troubleshooting

Issue: "Access Denied" when testing the policy

Cause: The Application Access Policy may not be created correctly or the app consent is missing

Solution:

Verify admin consent was granted (check Enterprise Applications)
Verify the policy exists: Get-ApplicationAccessPolicy | Where-Object { $_.AppId -eq "eb6992c6-9e08-444d-be7d-17b490f2f3d3" }
Ensure the mailbox email address is spelled correctly in the policy

Issue: Cannot connect to Exchange Online PowerShell

Cause: Module not installed or insufficient permissions

Solution:

Install module: Install-Module ExchangeOnlineManagement -Force
Ensure you have Exchange Administrator or Global Administrator role
Try connecting with: Connect-ExchangeOnline -UserPrincipalName your-admin@yourcompany.com

Issue: Magic Suite still cannot access mailbox after configuration

Cause: Configuration may need time to propagate, or there's an issue with the setup

Solution:

Wait 5-10 minutes for changes to propagate across Microsoft's infrastructure
Verify IMAP is enabled: Get-CASMailbox your-mailbox@yourcompany.com | Select-Object ImapEnabled
Run the test again: Test-ApplicationAccessPolicy -Identity your-mailbox@yourcompany.com -AppId eb6992c6-9e08-444d-be7d-17b490f2f3d3
Contact Panoramic Data support if the issue persists

Connecting to IMAP servers

Basic Connectivity

Method 1: Authenticating with Username and Password

Method 2: Authenticating with OAuth2 (Client Credentials Grant for Microsoft 365/Azure)

AlertMagic Integration

Configuring Azure AD for Magic Suite IMAP Access

Why OAuth for IMAP?

Magic Suite Application Details

Configuration Steps

Step 1: Consent to Magic Suite Application

Step 2: Configure Exchange Online Access Policy

Step 3: Provide Configuration Details to Panoramic Data

How Magic Suite Authenticates

Security & Compliance

Access Control

Auditing

Revoking Access

✅ Configuration Checklist

Before Going Live

Frequently Asked Questions

Q: Can Magic Suite access all our mailboxes?

Q: What data can Magic Suite access?

Q: How do we know if Magic Suite is accessing our mailbox?

Q: What happens if we revoke access?

Q: Can we use a regular user mailbox instead of a shared mailbox?

Q: How long does the client secret last?

Troubleshooting

Issue: "Access Denied" when testing the policy

Issue: Cannot connect to Exchange Online PowerShell

Issue: Magic Suite still cannot access mailbox after configuration

References & Additional Resources

Search