OAuth inbox

TrakIT can read a mailbox and act on the emails sent to it, for example rates sent to a rate card by email. The OAuth Inbox page connects TrakIT to that mailbox: a Gmail account, or an Office 365 mailbox.

To open it, select Admin > SysAdmin Pages > OAuth Inbox. The page heading is Mailbox Authorisation. Only system administrators can open it.

The page has two tabs, Gmail and Office 365. It opens on Gmail.

How TrakIT uses the mailbox

Every 5 minutes, TrakIT reads up to 50 emails from each mailbox connected here:

1. It saves each email, with its attachments, on the Emails Received tab of the Message log.
2. It moves the email out of the mailbox: to the trash in Gmail, or to Deleted Items in Office 365.
3. It acts on the emails whose subject is a TrakIT command, and replies to the sender.

Because TrakIT takes every email out of the mailbox, connect a mailbox that is used only for TrakIT. In Gmail, TrakIT reads every email of the account apart from spam and trash, not only the inbox.

Gmail tab

TrakIT Support first sets up the Google connection for your installation. You then authorize TrakIT to read the Gmail account.

1. Select the Gmail tab.
2. Select Authorise. TrakIT takes you to Google.
3. Sign in with the Gmail account TrakIT should read, and allow the access TrakIT asks for.
4. Google brings you back to the page, which says You have authorised your GMail account successfully.

To stop TrakIT reading the account, select Disconnect and confirm. TrakIT withdraws its access at Google and forgets the account, and says GMail deauthorised successfully. If Google doesn’t confirm, TrakIT still disconnects, and asks you to remove TrakIT from the third-party connections of the Google account yourself.

Message	Means
An error when you select Authorise, instead of Google’s page	TrakIT Support hasn’t set up the Google connection for your installation yet.
Invalid state parameter. Possible CSRF attack.	The return from Google didn’t match the request TrakIT sent, for example because your session ended in between. Select Authorise again.
Failed to obtain access token: …	Google refused to give TrakIT access. Select Authorise again.

Office 365 tab

TrakIT reads a shared Office 365 mailbox in the background with app-only access, through the Microsoft app registration your installation uses for Microsoft sign-in. The tab shows its Application (Client) ID and Tenant. TrakIT Support sets these up: until then they show (not configured).

Set up the app registration

A Microsoft 365 (Entra ID) administrator does this once. The tab gives the same steps under How to set up the app registration (app-only access).

1. In the Microsoft Entra admin center, open the app registration whose Application (Client) ID the tab shows.
2. Create a new client secret, and copy its value straight away: Microsoft shows it only once.
3. Add the Microsoft Graph Mail.ReadWrite permission as an application permission, not a delegated one, and grant admin consent for your tenant.
4. Recommended: restrict the app to the one mailbox, with an application access policy in Exchange Online, so that it can’t read every mailbox of the tenant.
5. Check that the Tenant shown on the tab is your own tenant’s ID, not a shared value such as “common”. If it isn’t, ask TrakIT Support to change it.

Connect the mailbox

1. Select the Office 365 tab.
2. In Mailbox to read, enter the mailbox’s address.
3. In Client Secret, paste the secret. Next to it, Configured or Not configured shows whether a secret is stored. Leave it empty to keep the stored secret.
4. Select Save. TrakIT says Office 365 mailbox settings saved.
5. Select Test Connection. TrakIT says Connected successfully to the mailbox, or Connection failed: with Microsoft’s answer.

TrakIT reads the mailbox every 5 minutes from then on. To read it straight away, select Check Now: TrakIT says Office 365 mailbox checked. See the Action Log for details. The emails appear on the Emails Received tab, and TrakIT acts on them at its next run. The User Action Log shows how many emails were read, in its Check O365 entries.

To stop TrakIT reading the mailbox, clear Mailbox to read and select Save.

Message	Means
Please specify a mailbox address.	Enter Mailbox to read before Test Connection.
No Microsoft sign-in settings found …	Your installation has no Microsoft sign-in set up. Ask TrakIT Support.
Connection failed: …	Microsoft refused access. Check the client secret, the Mail.ReadWrite permission and admin consent, and the mailbox address.

Who can use this page

Only system administrators can open the OAuth Inbox page. The menu entry is under SysAdmin Pages, which only system administrators see.