Airmail Crashes When Adding Outlook.com or Microsoft 365 Account — OAuth Setup Guide

Some users have reported that Airmail crashes during the process of adding an Outlook.com, Outlook.es, Hotmail, Live, or Microsoft 365 (work/school) account. In most cases this is caused by an incorrect setup method, a partial previous account entry, or by an OAuth permission step that has not been fully completed. This guide explains the recommended setup procedure and the troubleshooting steps to follow if the application becomes unstable while connecting a Microsoft account.

Why this can happen

Microsoft has progressively deprecated basic IMAP/SMTP authentication for personal and business accounts and now requires modern OAuth 2.0 sign-in. When an account is added through the generic IMAP option rather than the dedicated Outlook / Microsoft option, the authentication handshake may fail or remain in an inconsistent state, which in some configurations causes Airmail to terminate unexpectedly. Partial account records left behind after a failed attempt can also trigger crashes on subsequent retries.

Recommended setup procedure

1. Open Airmail and go to Airmail Settings > Accounts.
2. 2. If a partial or previous entry of this account already exists, remove it and quit Airmail completely before starting again.
3. 3. Reopen Airmail and choose Add Account.
4. 4. Select the dedicated "Outlook / Microsoft" option — this uses Microsoft's OAuth 2.0 sign-in and is the recommended and supported method for outlook.com, outlook.es, hotmail.com, live.com and Microsoft 365 addresses. Do not use the generic IMAP option for these providers.
5. 5. Complete the Microsoft sign-in inside the secure browser window that Airmail opens, including any two-factor authentication prompts and any permission requests presented by Microsoft.
6. 6. Wait for Airmail to finish the initial folder discovery before performing any other action.

Microsoft 365 (work or school) accounts

If the account belongs to a Microsoft 365 work or school tenant, administrator approval may be required before Airmail can complete the sign-in. In this case, please confirm with your IT administrator that third-party OAuth applications are permitted for your tenant. Without this approval, the OAuth flow will be interrupted and the account cannot be added.

If Airmail still crashes

If the crash persists after following the steps above, please collect the following information and share it with the Airmail Support team so our engineering team can investigate:

• The exact Airmail version installed (Airmail menu > About Airmail).
• - The platform and OS version on which the crash occurs (macOS / iOS / iPadOS, including the build number).
• - The exact error message displayed, if any.
• - The provider used (outlook.com, outlook.es, hotmail.com, live.com, or Microsoft 365).
• - A short description of the moment when the crash occurs (for example: immediately after entering the email address, after the Microsoft sign-in window, during folder discovery).

With these details, our technical team will be able to provide step-by-step instructions to restore the account or, if a software issue is confirmed, prioritise a fix.

If you have any further questions, feel free to reach out to the Airmail Support team.

Updated on: 05/08/2026