Accessing Shared Mailboxes in MS365

Microsoft 365 allows you to create shared mailboxes that are not bound to a specific user. Instead, one or multiple users can access these mailboxes using their own credentials to send and receive emails on behalf of the shared mailbox.

EmailEngine enables you to interact with these shared mailboxes through its API by leveraging OAuth2 authentication. This means you can programmatically access shared mailboxes without needing separate credentials for each one.

• Main User Account: You must have the main user account (with access to the shared mailboxes) added to EmailEngine.
• OAuth2 Application: An OAuth2 application configured in both Azure and EmailEngine.
• Permissions: Ensure that the main account has the necessary permissions to access the shared mailboxes.

Before accessing shared mailboxes, add the main user's Microsoft 365 account to EmailEngine using the standard account creation process. This account should have access to all the shared mailboxes you intend to use.

Refer to the EmailEngine API documentation for detailed instructions on adding a new account.

To add a shared mailbox to EmailEngine, you'll use an API call that specifies the shared mailbox and instructs EmailEngine to use the main account's credentials.

API Call Payload

Here's how to structure your API call:

• account: A unique identifier for the shared mailbox in EmailEngine (e.g., "shared").
• name: A friendly name for the mailbox (e.g., "Shared Account").
• email: The email address of the shared mailbox (e.g., "shared@example.com").
• oauth2.auth.delegatedUser: The email address or MS365 user ID of the shared mailbox.
• oauth2.auth.delegatedAccount: The EmailEngine account ID of the main user (e.g., "my-account").

Request — POST /v1/account

{
  "account": "shared",                     // optional; null ⇒ auto-generated
  "name": "Shared Account",
  "email": "shared@example.com",
  "oauth2": {
    "auth": {
      "delegatedUser": "shared@example.com",
      "delegatedAccount": "my-account"
    }
  }
}

In this example, EmailEngine connects to Microsoft 365 servers and authenticates as "shared@example.com" using the OAuth2 tokens from the main account "my-account".

If your main account uses IMAP and SMTP protocols, you can access shared mailboxes without additional configuration.

• IMAP Access: EmailEngine accesses the shared mailbox's emails using IMAP.
• SMTP Limitations: Shared mailboxes without a full MS365 subscription lack SMTP access.

Handling Sent Emails

When sending emails from a shared mailbox:

• SMTP Authentication: EmailEngine uses the SMTP credentials of the main account.
• From Address: The "From" address is set to the shared mailbox's email.
• Sent Items Duplication:
  • A copy of the sent email is saved in the shared mailbox's "Sent Items" folder.
  • Another copy is saved in the main account's "Sent Items" folder.
  • Result: Duplicate emails in "Sent Items" folders.

If you prefer to use the Microsoft Graph API, additional configuration is required.

Step 1: Update API Scopes in Azure

Add the following scopes to your Azure OAuth2 application:

1. Access Azure Portal: Log in to Azure Portal and navigate to your app.
2. API Permissions: Go to API Permissions > Add a permission > Microsoft Graph > Delegated permissions.
3. Add Scopes:
   • User.ReadBasic.All
   • Mail.ReadWrite.Shared
   • Mail.Send.Shared

Step 2: Update Scopes in EmailEngine

1. Navigate to OAuth2 Application: In EmailEngine, go to your OAuth2 application's settings.

2. Edit Additional Scopes:

   • Find the Additional Scopes section.

   • Add the following scopes:

     User.ReadBasic.All
     Mail.ReadWrite.Shared
     Mail.Send.Shared

3. Save Changes: Click Save to apply the new scopes.

Step 3: Refresh OAuth2 Grant for Main Account

To use the new permissions, update the OAuth2 grant for the main account.

• Option 1: Re-add the Main Account
  • Delete and re-add the main account in EmailEngine.
• Option 2: Generate a New Authentication URL
  1. Create Authentication Link:
     • Use the Authentication Form API.
     • Set account to your main account's ID (e.g., "my-account").
     • Set type to your OAuth2 application's ID in EmailEngine.
  2. User Authentication:
     • Provide the link to the main account user.
     • The user must open the link and grant the new permissions.

Step 4: Add or Reconnect Shared Mailboxes

With updated permissions:

• Add New Shared Mailboxes: Use the Account API as previously described.
• Reconnect Existing Mailboxes: If shared mailboxes were added before, use the Reconnect API to refresh their access.

If you only need the shared mailbox, create one EmailEngine account for it and let an authorised user grant consent during OAuth 2.0 login.

Request — POST /v1/account

{
  "account": "shared",                     // optional; null ⇒ auto-generated
  "name":   "Shared mailbox",
  "email":  "shared@example.com",

  "oauth2": {
    "provider":   "AAABkwrwyA8AAAAm",      // ID of the MS365 OAuth2 provider in EmailEngine
    "authorize":  true,                    // ask EmailEngine to return an auth URL
    "redirectUrl":"https://emailengine.app/", // user is sent here after consent

    "auth": {
      "delegatedUser": "shared@example.com" // address or objectId of the shared mailbox
    }
  }
}

Response

{
  "redirect": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=e887..."
}

Send the redirect URL to a user who already has Full Access to the shared mailbox.
After they sign in and accept the scopes, EmailEngine stores the tokens and the new shared account appears in the account listing. A separate personal-mailbox account is not required.

Field notes

• account – unique EmailEngine ID; set null to auto-generate.
• email – email address of the shared mailbox. Usually identical to oauth2.auth.delegatedUser unless you provide an objectId in that field.
• oauth2.auth.delegatedUser – the shared mailbox’s address or objectId, not the credentials of the user who signs in.
• The signing-in user’s own mailbox is never added to EmailEngine; their login is used solely to authorise the shared mailbox.

Once consent is complete, call any EmailEngine REST endpoint against the "shared" account exactly as you would for a normal mailbox.