Connect Outlook.com or Microsoft 365

Use this page to connect an Outlook.com, Hotmail or Microsoft 365 mailbox to mail. You sign in to Microsoft in your browser and approve access. You type no password into mail, and WireCat's Microsoft app is built in, so you register nothing. When you finish, mail reads your mail into the local store and can send from the address.

Before you startCopy Anchor Link

1. Install mail (installation).
2. Outlook.com only: turn IMAP on. Microsoft has it off by default (Microsoft's page). With IMAP off, the browser sign-in works but the mail server refuses the token, so skip this step at your cost:
   1. Open outlook.live.com and sign in.
   2. Select Settings (the cog), then "Mail", then "Forwarding and IMAP".
   3. Turn on "Let devices and apps use IMAP" and select "Save".
3. Microsoft 365 work or school account: there is nothing to turn on in the mailbox. See work or school account for what an admin may need to allow.

Sign inCopy Anchor Link

Pick a profile name (outlook here) and use your own address:

mail outlook session start --address [email protected]

mail opens your browser on Microsoft's sign-in page. Sign in and approve access. The tab then says "Sign-in received; you can close this tab". Go back to the terminal: mail answers with the profile, signed_in, the login (auth is oauth, provider is microsoft, client is wirecat), the scopes it was given (IMAP.AccessAsUser.All and SMTP.Send) and the folders it found.

On a computer with no browser, for example over SSH, add --no-browser. mail prints the link instead; open it on any computer, sign in, and the terminal finishes the same way.

Read and sendCopy Anchor Link

mail outlook sync                                  # INBOX and Sent by default
mail outlook schedule command mail-outlook --every 5m -- sync   # sync every 5 minutes
mail outlook search messages invoice               # search what sync stored

Sending uses the same sign-in, over Microsoft's SMTP server with OAuth. mail files a copy in Sent. The commands are in usage and all commands.

Work or school account (Microsoft 365)Copy Anchor Link

Use the same command with your work address. Personal Outlook.com and Hotmail accounts are not affected by this section.

What you see, and whyCopy Anchor Link

WireCat's Microsoft app is not yet publisher-verified. A work or school account belongs to an organisation (a "tenant"), and Microsoft does not let ordinary users of another tenant approve a multi-tenant app that has no verified publisher. Instead the sign-in stops with a page that says "Need admin approval", or with the error AADSTS90094 (the administrator must grant consent). The browser shows this page, so mail itself prints no Microsoft error code. The page is not a fault in your account or in mail. An admin has to act once, then everyone in the organisation signs in as usual. Microsoft describes the rule on Configure risk-based step-up consent.

Pick one of the two options below and send it to your admin.

Option A: the admin allows WireCat's app for the organisationCopy Anchor Link

The admin opens this link in a browser and signs in with an admin account. Replace {tenant} with the organisation's domain (for example contoso.com) or its tenant id:

https://login.microsoftonline.com/{tenant}/v2.0/adminconsent?client_id=f7f05d3a-b948-4d50-b3ce-59c816ce69e9&scope=offline_access%20https://outlook.office.com/IMAP.AccessAsUser.All%20https://outlook.office.com/SMTP.Send&redirect_uri=http://localhost/callback

The format comes from Microsoft's admin consent protocol: the /v2.0/adminconsent endpoint with client_id, scope (space-separated, written %20 in a link) and a redirect_uri that is registered for the app. The account needs a role that may grant consent for the organisation, such as Cloud Application Administrator or Privileged Role Administrator (roles).

The admin sees Microsoft's consent page for WireCat. It lists the three permissions and marks the publisher as unverified. The admin selects "Accept". Microsoft then sends the browser to http://localhost/callback; the tab may show a connection error because nothing listens there, and that is expected. The consent is already saved.

To undo it, the admin opens the Microsoft Entra admin center, then "Entra ID", "Enterprise apps", "All applications", WireCat, "Permissions", the "Admin consent" tab, and selects "Revoke permission" on each entry. To remove the app from the organisation, the admin deletes WireCat from "Enterprise apps" instead (steps).

Option B: the organisation registers its own appCopy Anchor Link

If your organisation does not allow third-party apps, an admin registers a private app, which needs no publisher verification inside its own tenant:

1. In the Microsoft Entra admin center, register an application. Platform: "Mobile and desktop applications". Redirect URI: http://localhost/callback. Turn "Allow public client flows" to Yes.

2. Copy the Application (client) ID.

3. Each user sets it once, in a terminal:

   Copy Text

   mail config set --defaults microsoft_client_id <application-client-id>

The full steps, with the permissions to list, are in Microsoft app registration.

Sending can still failCopy Anchor Link

The organisation may also have "Authenticated SMTP" off for your mailbox. Security defaults, and organisations created after January 2020, have it off until an admin turns it on. Reading works either way; only sending fails.

If it does not workCopy Anchor Link

More errors: troubleshooting.

Advanced: your own Microsoft appCopy Anchor Link

Use this only if your organisation requires its own app. Register it (steps): platform "Mobile and desktop applications", redirect http://localhost/callback with no port, never "Web". Then set its id once, in a terminal:

mail config set --defaults microsoft_client_id <application-client-id>

Only you can set it; an agent over MCP is refused.