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").

Example Payload

{
  "account": "shared",
  "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.