Microsoft Graph Email Account Configuration

TraceGains supports connecting to email accounts through the Microsoft Graph API, providing a more secure and reliable method for mailbox access. Using Microsoft Graph helps reduce issues related to password expiration and improves long-term stability for email processing within TraceGains.

TraceGains will continue to support legacy protocols (POP3, IMAP4, SMTP). However, Microsoft Graph is the recommended option for customers using Microsoft Office 365.

Setting Up Your Office 365/Azure Tenant 

To allow TraceGains to access your Office 365 mailbox using the Microsoft Graph API, complete the steps below in your Microsoft Azure tenant.

App Registration

Step 1: In Azure, navigate to App registrations and click New registration.

Step 2: Enter a descriptive name such as “TraceGains Mail – Graph API” to make it easy to identify later, then click Register.

Step 3: Once you create the App registration, it will appear under the All applications sub-tab in the App registrations view. 

Click on the newly created App registration to open its configuration settings.

Create a Client Secret

Step 1: From the app configuration menu, select Certificates & secrets.

Step 2: Click + New client secret.

Step 3: Enter a descriptive name for the client secret (e.g., “TraceGains App Secret”). It’s recommended to include "TraceGains" in the name to improve identification if secrets are viewed in a consolidated list.

Choose an expiration period that aligns with your internal security policies, keeping in mind that this will apply to all TraceGains registered Email Service Accounts using this App registration.

Click Add to save.

Step 4: Once added, the secret will appear in the Client Secrets sub-tab under the Value column within the Certificates & secrets view.

Copy and save this secret somewhere secure—it will be used in the Password field for both inbound and outbound configurations in the Email Service Account settings. 

You will not be able to view it again after leaving this page.

Assign API Permissions

Step 1: In the app settings, open API permissions. Then, click Add a permission.

Step 2: Click Microsoft Graph.

Step 3: In the next Request API permissions view for Microsoft Graph, click on the Application permissions tile.

Step 4: Add the following permissions:

• Mail.ReadWrite – Allows TraceGains to read emails, mark messages as read, and move messages to Deleted Items.
• Mail.Send – Allows TraceGains to send email from the configured mailbox.

Use the search field to find each permission, select it, and click Add permissions.

Step 5: Click Grant admin consent for <your tenant> to authorize the permissions.

In the pop up, click Yes.

Once admin consent is granted, the app registration setup is complete.

(Optional) Restrict Mailbox Access with an Application Access Policy

For additional security, you may choose to restrict the Graph app’s access to only specific mailboxes.

This can be done by:

1. Creating a mail-enabled security group

2. Adding the email accounts TraceGains should access

3. Creating an Application Access Policy in PowerShell that restricts access to that group

This step is optional and recommended if you have strict mailbox security requirements.

Record Required IDs

From the app’s Overview page, record the following values:

• Application (client) ID

• Directory (tenant) ID

Along with the Client Secret, these values are required to configure the Email Account in TraceGains.

Configure Email Accounts in TraceGains

Step 1: Log in to TraceGains and navigate to Configuration > Email Accounts. Then, click New.

Step 2: Enter a Name for the new account.
If you already have a non-Graph account, consider using the same name with “Graph” added.

Then, click Save. 

Do NOT set inbound or outbound to "Activate" yet. This allows you to test the new account without impacting existing configurations.

Step 3: Complete the following:

• Populate:
  • Inbound Configuration only for accounts that need inbound email processing (e.g., inbound COAs, CARs)
  • Outbound Configuration credentials for all email accounts
• The email address must be the primary mailbox address, not an alias
• Set Protocol to GRAPH

• Enter:

  • Tenant ID (the Directory ID value you obtained from configuring the Office365/Azure tenant)

  • Client ID (the Application ID value you obtained from configuring the Office 365/Azure tenant)

  • Client Secret

•  If this account will send system notifications, enable Use for Notification.

Test the Email Account Connection

Use the green down-arrow icons to test both:

• Inbound configuration

• Outbound configuration

A successful outbound test will send a system-generated email to the mailbox.

Once both tests succeed, you can proceed with activation.

Deactivate Old Accounts and Activate the Graph Account

1. Open your existing (non-Graph) email accounts and uncheck Active

2. Click Save

3. Return to the new Graph email account

4. Check Activate

5. Click Save

Your TraceGains instance is now connected to Office 365 using the Microsoft Graph API.