TraceGains now supports connecting to email accounts through the Microsoft Graph API, offering a more secure method of mailbox access. This replaces older, less secure protocols such as POP3, IMAP4, and SMTP. The Graph API helps prevent issues like password expiration and enhances email management within your TraceGains system.
Setting Up Your Office 365/Azure Tenant
To allow TraceGains to access your Office 365 mailbox using the Microsoft Graph API, you’ll need to complete a series of steps in your Office 365/Azure tenant.
Step 1: Go to App registrations in Azure and click New registration.
Step 2: Name your app something like “TraceGains Mail - Graph API” for easy identification, then click Register to create your app.
Step 3: Once you create the App registration, it will appear under the Owned 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: In the app settings, click on Certificates & Secrets.
Step 2: Click New client secret to create a password for the app.
Step 3: Enter a descriptive name for the client secret (e.g., “TraceGains Secret”). It’s recommended to include "TraceGains" in the name to improve identification if secrets are viewed in a consolidated list.
Choose an expiration policy 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 the secret.
Step 4: Once added, the secret will appear in the Certificates & secrets view under the Value column. 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, go to API permissions. Then, click Add a permission.
Step 2: In the Request API permissions view, click the Microsoft Graph tile.
Step 3: In the next Request API permissions view for Microsoft Graph, click on the Application permissions tile.
Step 4: TraceGains will need the following application-level permissions to function properly:
- User.Read.All – Allows TraceGains to query the tenant directory for a user using a registered email in an active Email Service Account.
- Mail.ReadWrite – Enables TraceGains to download, mark as read, and move emails to Deleted Items within a user’s mailbox.
- Mail.Send – Grants TraceGains permission to send emails from a user’s mailbox.
Type the permission name in the Select permissions search, check the box, and click Add permissions. Repeat for all required permissions.
Step 5: Click Grant admin consent for <name> to allow the app to query the directory and access a mailbox in the context of a user entity.
After administrative consent has been granted, the App registration setup is complete.
Record Important Information
Write down the Application (client) ID and Directory (tenant) ID from the Overview section of your app. These 2 values along with the Client secret recorded earlier are required for the Email Service Account configuration in your TraceGains instance.
Configuration - Email Accounts
Now it's time to set up your email account in TraceGains.
Step 1: Log into TraceGains. Go to Configuration > Email Accounts. Click New.
Step 2: Type a Name for the new Graph API version of your mailbox configuration. If you have an existing non-Graph account already configured, you may want to copy the same name followed by "Graph".
Then, click Save. Do NOT set inbound or outbound to "Activate" yet. Using this approach will allow you to maintain your existing live account(s) while adding/testing the new Graph API account version.
Step 3: Complete the following:
- Toggle the Protocol drop-down and select GRAPH.
- Enter the Application (client) ID, Directory (tenant) ID, and Client secret from your Office 365/Azure tenant setup into the corresponding fields.
- Populate:
- Outbound Configuration credentials and Email Address for ALL email accounts.
- Inbound Configuration only for accounts that need inbound email processing (e.g., inbound COAs, CARs).
- If you want to use this account for sending notifications, make sure to check Use for Notification.
- The email address must be the primary email, not an alias.
Test the Email Account Connection
After completing the Manage Email Account setup, test the Graph API connection by clicking the green down arrow for both inbound and outbound configurations. A successful outbound test will generate a system email in your inbox. If both tests pass, you can proceed with inactivating your other accounts.
Deactivating Old Email Accounts and Activating New Graph Accounts
Once your new Graph API email account is set up and tested:
- Go to your old email accounts in TraceGains and uncheck Active.
- Save the changes.
- Then, go back to your new Graph API account and check Activate.
- Save the changes, and your new account will be active!
Your TraceGains instance is now connected to your Office 365 mailbox using the Microsoft Graph API for more secure and efficient email management.