Outlook / Hotmail OAuth Setup

How the OAuth flow works

1. Admin (one-time): registers a Microsoft App in Azure Entra ID and pastes the App's Client ID + Client Secret into MailTrixy.
2. User (every workspace): goes to Settings → Email Accounts → clicks “Sign in with Outlook”.
3. Microsoft's login page opens. User signs in, grants MailTrixy permission to read and send mail on their behalf.
4. Microsoft redirects the browser back to MailTrixy with a one-time authorisation code. MailTrixy exchanges it for a long-lived access token + refresh token, stored encrypted in the database.
5. MailTrixy uses the tokens to call graph.microsoft.com for sending and receiving mail. Tokens are refreshed automatically before they expire.

Step 1: Create the Microsoft App

1. Open portal.azure.com and sign in with the Microsoft account you want to own the app.
2. In the top search bar, type Microsoft Entra ID and click it.
3. In the left menu, click App registrations → New registration.
4. Fill in:
   • Name: MailTrixy (or your platform's name).
   • Supported account types: “Accounts in any organizational directory and personal Microsoft accounts (e.g., Skype, Xbox)” — this is required for outlook.com / hotmail.com users to be able to log in.
   • Redirect URI: Platform = Web, URI = https://YOUR-DOMAIN/email-oauth/microsoft/callback
5. Click Register.

The redirect URI must be HTTPS (except http://localhost for local development), no trailing slash, all lowercase, exact path /email-oauth/microsoft/callback. Any mismatch = invalid_request error.

Step 2: Create a Client Secret

1. Inside your new app, click Certificates & secrets in the left menu.
2. Click + New client secret.
3. Description: MailTrixy production. Expires: 24 months (you'll need to renew it before expiry — mark a calendar reminder).
4. Click Add.
5. Copy the Value column immediately (long string starting with letters). Not the Secret ID column. This value is shown only once.

Step 3: Grant API Permissions

1. Click API permissions in the left menu.
2. Click + Add a permission → Microsoft Graph → Delegated permissions.
3. Search and tick these scopes:
   • Mail.ReadWrite
   • Mail.Send
   • User.Read
   • offline_access (this enables refresh tokens)
4. Click Add permissions. The four scopes appear in the list with “User consent” type (no admin consent required for these).

Step 4: Paste credentials into MailTrixy

1. Back at Azure, in your app's Overview page, copy the Application (client) ID — a UUID like aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee.
2. Log into your MailTrixy admin panel.
3. Go to Admin → Settings → Integrations.
4. Paste the Application (client) ID into the Microsoft Client ID field.
5. Paste the secret Value (from Step 2) into the Microsoft Client Secret field. (It's encrypted before being stored.)
6. Click Save.

Step 5: Test the connection

1. Log out of admin, log back in as a regular workspace user (or stay as admin, switch workspace).
2. Go to Settings → Email Accounts → Add Account.
3. Click the Sign in with Outlook button (the blue Microsoft logo tile, marked PREFERRED).
4. Microsoft's login screen opens. Sign in with any outlook.com, hotmail.com, live.com, msn.com, or Microsoft 365 work address.
5. On the consent screen, click Accept.
6. You're redirected back to MailTrixy with a green “Outlook connected successfully!” message. Initial inbox sync begins immediately.

Troubleshooting

“invalid_request: The provided redirect_uri is not valid”

The redirect URI you registered in Azure doesn't match the one MailTrixy is sending. Check:

• Must be HTTPS (Azure rejects HTTP unless localhost).
• No trailing slash. /callback not /callback/.
• All lowercase, exact path /email-oauth/microsoft/callback.
• You clicked Save at the bottom of the Authentication page after adding the URI.
• The Microsoft Client ID in MailTrixy actually matches the Azure app you edited (not a different app you have lying around).

Personal Microsoft account can't sign in

Go back to Azure → your app → Authentication → Supported account types. Make sure it's set to “Accounts in any organizational directory and personal Microsoft accounts”. Save.

Stuck on the consent screen

Verify the four permissions (Mail.ReadWrite, Mail.Send, User.Read, offline_access) are listed under API permissions. Without offline_access, tokens expire after an hour and never refresh.

“invalid_client” on callback

The Client Secret in MailTrixy doesn't match Azure. Most common cause: you pasted the Secret ID (the GUID column) instead of the Value (the long string column starting with letters). Go back to Azure → Certificates & secrets — the Value column shows the actual secret only once when you create it. If you've lost it, create a fresh secret and paste the new Value into MailTrixy.

Connected accounts disconnect after a few months

Your Azure App's Client Secret expired. Azure secrets have a max lifetime (typically 24 months). Renew it: Certificates & secrets → New client secret → copy the new Value into MailTrixy Admin Settings. Existing user connections continue working with the new secret because they use refresh tokens (which don't expire).