Auditoria.AI Mailbox Integration – OAuth Overview

Introduction

The mailbox integration feature in Auditoria.AI enables you to connect your organization’s email systems directly to the Auditoria platform. This integration is central to automating email‑driven workflows such as:

• Receiving and processing vendor and customer emails
• Sending automated or assisted replies
• Tagging and tracking finance- and operations‑related conversations

By connecting supported mailboxes—including standard, shared, and collaborative mailboxes in both Google Workspace and Microsoft 365—Auditoria SmartBots can:

• Securely access incoming emails
• Send outbound responses
• Tag and label conversations
• Execute business logic, routing, and approvals

This integration removes the need for users to manually manage email threads, improves response consistency, and ensures that communications are handled according to your organization’s rules and permissions.

Auditoria.AI mailbox integration supports a range of deployment patterns, from a direct mailbox connection for a single Bot user to shared group mailboxes for collaborative workflows. These patterns help you automate routine tasks and track communications at scale while maintaining security, compliance, and visibility across business processes.

Supported Mailboxes and Integration Capabilities

Auditoria.AI supports integration with the leading enterprise email providers:

• Google Workspace (Gmail)
• Microsoft 365 (Exchange Online / Outlook)

You can connect the following mailbox types:

Standard Mailboxes

• What they are: Individual user mailboxes used for direct, one‑to‑one or role‑based communications.
• Where supported: Gmail / Google Workspace and Microsoft 365.
• How Auditoria.AI uses them: A standard mailbox can be connected directly as a Bot Mailbox. SmartBots then read and send email using that address.

Shared Mailboxes (Microsoft 365)

• What they are: Shared mailboxes (for example, ap@company.com, ar@company.com, support@company.com) that multiple users can read and send from.
• Where supported: Microsoft 365.
• How Auditoria.AI uses them: Auditoria connects using a licensed standard mailbox (Bot mailbox) that has been granted delegated access (Full Access / Send As) to the shared mailbox, following Microsoft best practices. Auditoria never logs in directly to an unlicensed shared mailbox with a password.
• See Microsoft documentation for a general overview: About shared mailboxes - Microsoft 365 admin

Collaborative Inboxes (Google Groups)

• What they are: Google Groups configured as Collaborative Inboxes used for team‑based email management (for example, ap@company.com or helpdesk@company.com).
• Where supported: Google Workspace.
• How Auditoria.AI uses them: A standard Gmail mailbox is added as a member of the collaborative group and then connected to Auditoria as a Bot Mailbox. Auditoria accesses emails via the member mailbox using the Gmail API.
• Google overview: Make a group a Collaborative Inbox - Google Workspace Learning Center

Integration Capabilities

For all supported mailbox types, Auditoria.AI (subject to configuration and granted permissions) can:

• Read and retrieve incoming emails
• Send outbound responses
• Tag or categorize email threads
• Track, associate, and forward messages as per workflow rules
• Mark emails as read or unread

Supported deployment patterns include:

• Direct Bot Mailbox (standard mailbox only)
• Shared mailbox via Bot mailbox (Microsoft 365)
• Collaborative inbox via member mailbox (Google Workspace)

This flexibility allows your organization to choose mailbox patterns that align with your IT policies and collaboration needs.

Microsoft 365 Mailbox Integration

Supported Microsoft 365 Plans

Auditoria.AI supports Microsoft 365 Business and Enterprise plans that include Exchange Online.

Common patterns:

1. Direct standard mailbox as Bot Mailbox
   • Example: ap-bot@company.com
   • Auditoria connects directly to this mailbox via OAuth 2.0 / Microsoft Graph.
2. Shared mailbox via Bot Mailbox
   • Example:
     • Shared mailbox: ap@company.com
     • Bot mailbox: ap-bot@company.com
   • The Bot mailbox is a licensed user mailbox. It is added as a member of the shared mailbox with:
     • Full Access (read and manage items)
     • Send As or Send on Behalf (optional, but required if the Bot should send email as the shared address)
   • Auditoria connects via OAuth to the Bot mailbox and, through delegated rights, reads and sends on behalf of the shared mailbox.

This pattern aligns with Microsoft and enterprise IdP (for example, Okta) best practices:

• Shared mailboxes remain unlicensed and no passwords are set on them.
• All authentication and MFA/SSO enforcement occurs on the licensed Bot user mailbox.

Microsoft 365 OAuth 2.0 – Technical Overview

This section addresses the main question often raised by security and IT teams: “How does Auditoria.AI technically connect to Microsoft 365 mailboxes using OAuth?”

Auditoria uses the OAuth 2.0 authorization code flow with the Microsoft identity platform (Azure AD) and the Microsoft Graph API.

1. Authentication Model

• Identity provider: Microsoft Entra ID (formerly Azure AD).
• Flow: OAuth 2.0 authorization code flow with a confidential client.
• APIs: Microsoft Graph for mail access.
• Key properties:
  • No Exchange passwords are sent to or stored by Auditoria.
  • All user sign‑in and consent screens are Microsoft‑hosted.
  • Tokens are used to call Microsoft Graph; Auditoria never accesses Exchange via IMAP/POP with credentials.

2. End-to-end OAuth Flow

When an administrator or authorized user connects a Microsoft 365 mailbox in Auditoria.AI:

1. User starts connection in Auditoria
   • From System Settings > Mailbox Configuration, they select Microsoft 365 / O365 and specify:
     • The Bot mailbox (for example, ap-bot@company.com).
     • Optionally, a Shared mailbox address if using the shared mailbox pattern.

2. Redirect to Microsoft sign‑in and consent

2. User authentication and consent
   • The user signs in using their corporate Microsoft 365 account (or is already signed in).
   • Microsoft presents a consent screen describing what the Auditoria app will be allowed to do, for example:
     • Read and manage mail in the signed‑in user’s mailbox.
     • Send mail as the user.
   • Depending on tenant configuration, consent may require an administrator to approve on behalf of the organization.
3. Authorization code callback
   • On approval, Microsoft redirects back to Auditoria’s OAuth callback URL with:
     • code (authorization code)
     • state (to confirm request integrity)
   • Auditoria:
     • Verifies that state matches the original session.
     • Handles any error parameters.
     • Proceeds to exchange the code for tokens.
4. Token exchange
   • Auditoria’s backend service calls the Microsoft token endpoint:
     POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
   • The response returns:
     • An access token (short‑lived).
     • Optionally, a refresh token (used to obtain new access tokens without user interaction).
     • Scope and expiry information.
5. Using tokens to access the mailbox
   • Auditoria uses the access token to call Microsoft Graph APIs such as:
     • GET /me/messages
     • GET /users/{shared-mailbox-id}/messages (via delegated rights when using a shared mailbox)
     • POST /sendMail for sending replies or outbound notifications.
   • For shared mailboxes:
     • Auditoria authenticates as the Bot user.
     • Because the Bot has Full Access / Send As rights, it can read and send on behalf of the shared mailbox using Microsoft Graph.
6. Token refresh and revocation
   • When the access token expires:
     • Auditoria uses the refresh token (if allowed by policy) to request a new access token.
     • If refresh fails (for example, consent revoked, account disabled, app blocked), Auditoria marks the mailbox as disconnected and surfaces an error so an admin can reauthorize.
   • If an administrator revokes the app or changes consent in Azure AD:
     • All subsequent Graph calls fail until re-authorized, effectively revoking Auditoria’s access.

Microsoft 365 permissions

1. Microsoft Graph OAuth

Auditoria uses a least‑privilege model and, for typical production integrations, requests delegated Microsoft Graph scopes such as:

• Mail.Read – Read mail in the signed‑in user’s mailbox and any shared mailbox the user has access to.
• Mail.ReadWrite – Read and modify mail (for example, mark as read, move messages, or apply categories), where automation requires such actions.
• Mail.Send – Send mail as the signed‑in user (or as a shared mailbox when Send As is configured).
• offline_access – Obtain refresh tokens to maintain access without repeated user prompts.

Key points:

• Permissions are delegated, not tenant‑wide application permissions, in standard deployments.
• Auditoria can only access:
  • The Bot mailbox.
  • Shared mailboxes and folders that the Bot mailbox has been explicitly granted access to in Exchange Online.

Administrators can review and manage these scopes in the Azure portal under Enterprise applications.

2. Exchange Mailbox Delegation (shared mailbox pattern)

For shared mailboxes, the following Exchange Online permissions are relevant:

• Full Access
  • Allows the Bot user to open the shared mailbox and read, view, and manage all items.
• Send As
  • Allows the Bot user to send messages that appear to come directly from the shared mailbox address (for example, From: ap@company.com).
• Send on Behalf
  • Allows the Bot user to send messages “on behalf of” the shared mailbox (for example, From: ap-bot@company.com on behalf of ap@company.com).

Recommended setup:

1. Create a licensed Bot user mailbox (for example, ap-bot@company.com).
2. Grant Full Access + Send As on the shared mailbox to the Bot user in the Microsoft 365 admin center.
3. Connect the Bot mailbox to Auditoria using Microsoft 365 OAuth.
4. In Auditoria’s mailbox configuration, specify that this Bot mailbox uses a Shared mailbox and provide the shared mailbox address.

This pattern follows Microsoft and enterprise IdP (Okta, etc.) best practices and avoids direct password access to shared mailboxes.

Data Access, Usage, and Security

1. Data Accessed

Using Microsoft Graph and the granted scopes, Auditoria may access:

• Email metadata
  • Subject, sender, recipient(s)
  • Timestamps
  • Message identifiers and folder information
• Email content (as required for automation)
  • Message body text
  • Attachments (for example, invoices, remittance advices, statements)
• Mailbox structure
  • Folders and categories used in workflows

Auditoria does not, by default:

• Access other Microsoft 365 workloads (for example, calendar, contacts) unless explicitly required.
• Broadly enumerate or modify user directories beyond what is required for mail workflows.

2. How Data is Used

Auditoria uses mailbox data to:

• Identify finance‑related messages (AP/AR/vendor/customer communication).
• Extract invoice, remittance, and payment details from emails and attachments.
• Classify and route messages (for example, which SmartFlow, which queue, which analyst).
• Automate responses and follow‑ups under configured business rules.

3. Token and Data Security

• Token storage
  • Access and refresh tokens are stored only on backend services in secure, access‑controlled storage.
  • Tokens are encrypted at rest and never exposed to client browsers or user devices.
• Least-privilege design
  • Auditoria requests only the scopes needed for the configured features.
  • Customers can adjust or restrict scopes according to their policies, with corresponding functional trade‑offs.
• Isolation and auditability
  • Each customer’s environment is logically isolated.
  • Auditoria maintains logs for operational and audit purposes consistent with its security and compliance posture (for example, SOC 2‑aligned hosting).

Google Workspace (Gmail) Mailbox Integration

For completeness, below is a high‑level summary of how Auditoria integrates with Gmail.  

1. Supported Patterns

• Standard mailbox
  • Direct connection using Gmail OAuth and the Gmail API.
• Collaborative inbox (Google Group)
  • A standard mailbox (Bot mailbox) is added as a member of the collaborative group.
  • Auditoria connects to the Bot mailbox and processes messages that are delivered there as part of the group.
  • Auditoria also checks the mailbox’s sendAs settings as part of collaborative mailbox detection and classification.

Note: Gmail’s APIs do not support accessing delegated mailboxes in the same way Outlook / Microsoft Graph does. Instead, Auditoria relies on group membership and sendAs settings for collaborative mailboxes.

2. OAuth (Gmail)

Auditoria uses Google’s OAuth 2.0 authorization code flow for Gmail integration.

For Gmail, Auditoria requests the full-access Gmail:

• https://mail.google.com/ – Full access to Gmail, including reading, modifying, labeling, and sending messages.

The conceptual model is similar to Microsoft 365:

• User is redirected to Google’s sign‑in and consent page.
• Auditoria exchanges the authorization code for tokens.
• Gmail API is called using those tokens; no passwords are stored.

See Google’s guide for collaborative inboxes: Make a group a Collaborative Inbox - Google Workspace Learning Center

Security, Data Handling, and Compliance

1 Token Security

• Tokens are stored only on secure backend services, never in browser storage.
• Access and refresh tokens are encrypted at rest and restricted to the components that need them.
• Auditoria follows standard best practices for token lifecycle:
  • Short‑lived access tokens.
  • Controlled refresh.
  • Revocation by admins via Azure AD or Google Workspace.

2 Data Access

Using the granted permissions, Auditoria accesses only the email data required to support configured workflows, such as:

• Email metadata (subject, sender, recipients, timestamps)
• Message content and attachments relevant to automation (for example, invoices, remittance advices, statements)
• Folder and labeling information used to route or track messages

Auditoria does not access other services (for example, calendars or contacts) unless specifically authorized.

3 Compliance and Governance

• Each customer is logically isolated.
• Email processing activities can be logged for operational support and audit, consistent with customer policies.

Troubleshooting – Common Microsoft 365 Issues