hub/docs/mail-setup.md

Setting up Outlook.com mail (Microsoft app registration)

NE Hub reads and sends your Outlook.com (personal) mail through Microsoft Graph. Microsoft requires every app that does this to be registered once. It is free and takes about five minutes. The steps follow the Entra portal; Microsoft changes the layout now and then, so a label may differ slightly.

1. Open the registration page

1. Go to entra.microsoft.com and sign in with any Microsoft account. It does not have to be the mailbox you will read.
2. If it says you need a directory or Azure subscription, accept the free "Default Directory" it offers. The free tier is enough and costs nothing.
3. In the left menu open Entra ID -> App registrations -> New registration.

2. Fill in the registration

• Name: NE Hub.
• Supported account types: choose Personal Microsoft accounts only. This matches the hub, which signs in through Microsoft's "consumers" endpoint.
• Redirect URI: set the platform to Web and enter https://hub.necloud.us/api/mail/callback. Use your real hub address. It must match PUBLIC_URL in your .env exactly: same https, same host, no trailing slash.
• Press Register.

3. Copy the client ID

On the app's Overview page, copy the Application (client) ID (a long GUID). It goes in MS_CLIENT_ID.

4. Add the mail permissions

1. Open API permissions -> Add a permission -> Microsoft Graph -> Delegated permissions.
2. Tick these four and press Add permissions:
   • Mail.ReadWrite
   • Mail.Send
   • User.Read
   • offline_access
3. You do not need "Grant admin consent". Personal accounts approve these themselves the first time they connect.

5. Create a client secret

1. Open Certificates & secrets -> New client secret.
2. Give it any name and choose the longest expiry (24 months).
3. Copy the Value column right away. Microsoft shows it only once. It goes in MS_CLIENT_SECRET (not the "Secret ID").
4. Put a reminder in your calendar for about 23 months from now. When the secret expires, Connect fails until you make a new one and update MS_CLIENT_SECRET.

(If you would rather not have a secret, register the redirect under the platform Mobile and desktop applications instead of Web and leave MS_CLIENT_SECRET empty. The hub signs in with PKCE either way.)

6. Give the hub the values

Add these to your .env (or your stack's environment settings):

MS_CLIENT_ID=<the Application (client) ID>
MS_CLIENT_SECRET=<the secret Value>
PUBLIC_URL=https://hub.necloud.us

Then redeploy the hub:

docker compose up -d

Leave MS_CLIENT_ID empty to switch Mail off.

7. Connect

1. Open the hub, go to Mail, and press Connect Outlook.com.
2. Sign in with your Outlook.com account on Microsoft's page and approve the permissions.
3. You land back on the Mail tab with your inbox showing.

Each person who has the Mail tab connects their own mailbox. The hub keeps only the sign-in token, encrypted, in that person's own folder.

If something goes wrong

• "redirect URI doesn't match" (AADSTS50011): the address in step 2 differs from what the hub sends. Compare PUBLIC_URL and the registered URI character by character.
• "invalid client secret" or invalid_client: you pasted the Secret ID instead of the Value, or the secret has expired. Make a new one.
• "app not found in directory/consumers": the account type was not set to personal accounts only. Check it under Authentication -> Supported account types.
• The Mail tab says "Mail is not set up on this server": MS_CLIENT_ID is empty or the container was not restarted after you added it.
• Connect works, then later says Microsoft signed you out: the sign-in token was revoked, for example after a password change. Press Connect again.
• Installed iPhone/iPad app: Microsoft's page may open in Safari. Sign in there, then reopen the app.