Using Apple Mail's Troubleshooting Tools

Here's what to do when something goes wrong with Apple Mail

A frustrated woman using a Mac notebook computer.

Rafal Rodzoch / Getty Images

​The Apple Mail application that comes on every Mac is straightforward to set up and use. Along with helpful guides that step through the process to create accounts, Apple also provides a few troubleshooting features designed to help when something isn't working. The three main features that diagnose problems are the Activity window, the Connection Doctor, and Mail logs.

Instructions in this article apply to the Mail application on Mac computers running OS X Mavericks through macOS Mojave or on Macs running OS X Mountain Lion and earlier, as specified.

Use the Apple Mail Activity Window (OS X Mavericks and Later)

The Activity window displays the status when sending or receiving mail for each mail account. It's a quick way to see what may be going on, such as an SMTP (Simple Mail Transfer Protocol) server refusing connections, an incorrect password, or timeouts because the mail server can't be reached.

To find the Activity window, go to the Apple Mail menu and select Window > Activity.

Mac mail on laptop screen
iStock

The Activity window has changed over time. Earlier versions of the Mail app had a more useful and helpful activity window, but even with the trend to reduce the information provided in the Activity window, it remains one of the first places to look for issues. 

The Activity window doesn't offer a method to correct problems, but status messages alert you when something goes wrong with your mail service and usually helps you figure out what it is. If the Activity window shows problems with one or more Mail accounts, try the other two troubleshooting aids provided by Apple to solve the problem.

Use Apple Mail Connection Doctor (OS X Mavericks and Later)

The Apple Mail Connection Doctor can diagnose problems with Mail. The Connection Doctor confirms that the device is connected to the internet and checks each mail account to ensure it can connect to send and receive mail. The status for each account displays in the Connection Doctor window. If you're unable to connect to the internet, the Connection Doctor offers to run Network Diagnostics to track down the cause of the problem.

Apple Mail's Connection Doctor in use screenshot

Most Mail issues are account-related rather than internet connection related, however. To troubleshoot account issues, the Connection Doctor offers both an overview for each account and a detailed log of each attempt to connect to the appropriate email server.

Run Connection Doctor (OS X Mavericks and Later)

To run the Connection Doctor utility, go to the Mail menu and select Window > Connection Doctor. Connection Doctor automatically starts the checking process and displays the results for each account. Connection Doctor checks the ability of each account to receive mail and tests the ability of each account to send mail, so there may be two status listings for each mail account.

Any account with a status indicated in red has some type of connection issue. Connection Doctor includes a brief summary of the problem, such as an incorrect account name or password. To find out more about the account issues, view the details of each connection.

To view log details in the Connection Doctor:

  1. At the bottom of the Connection Doctor window, click Show Detail to open a tray that slides out from the bottom of the window and displays the contents of the logs.

  2. Scroll through the logs to find any errors and see a detailed explanation for any problems.

  3. Click Check Again to rerun the Connection Doctor and display the logs in the tray.

The one problem with the detail display in the Connection Doctor is that the text can't be searched, at least not from the Connection Doctor window. If you have multiple accounts, scrolling through the logs can be cumbersome. Instead, copy and paste the logs to a text editor, then search for specific account data, but there is another option — the Mail logs, which your system keeps tabs on.

Use Console to Review Mail Logs

While the Activity window provides a real-time look at what's occurring as you send or receive mail, the Mail logs go one step further and keep a record of each event. Because the Activity window shows activity in real-time, if you glance away or blink, you may miss seeing a connection issue. The Mail logs, on the other hand, keep a record of the connection process.

Mail Connection Doctor screenshot

Enable Mail Logs (OS X Mavericks and Later)

To open the Connection Doctor window in Mail, go to the Mail menu, select Window > Connection Doctor, then select the Log Connection Activity check box.

View Mail Logs (OS X Mavericks and Later)

In earlier versions of the Mac OS, Mail logs were viewed in the Console. As of OS X Mavericks, you can bypass the Console app and view the logs with any text editor, including the Console.

  1. In the Mail menu bar, go to Window > Connection Doctor.

    Connection Doctor item in Window menu in Mail on macOS
  2. Click Show Logs to open a Finder window containing individual logs for each Mail account that is set up on the Mac.

    Show Logs button in Mail Connection Doctor
  3. Double-click a log to open it in TextEdit. Or, right-click a log and select Open to open the log in the app of your choice.

    Mail log files in macOS

Enable Mail Logs (OS X Mountain Lion and Earlier)

In OS X Mountain Lion and earlier, Apple includes an AppleScript to turn Mail logging on. Once it's turned on, the Console logs keep track of your Mail logs until you quit the Mail application. If you want to keep Mail logging active, rerun the script each time before you launch Mail.

To turn on Mail logging:

  1. If Mail is open, quit Mail.

  2. Open the folder located at /Library/Scripts/Mail Scripts.

  3. Double-click the Turn on Logging.scpt file.

  4. If the AppleScript Editor window opens, click the Run button in the upper-left corner.

  5. If a dialog box opens that asks if you want to run the script, click Run.

  6. A dialog box opens, asking if you want to enable socket logging for checking or sending mail. Click Both.

  7. Logging is enabled, and the Mail application launches.

View Mail Logs (OS X Mountain Lion and Earlier)

Mail logs are written as Console messages that can be displayed in the Apple Console application.

  1. Launch Console, located at /Applications/Utilities/.

  2. In the Console window, expand the Database Searches area.

  3. Select the Console Messages entry.

  4. In the Filter field, enter com.apple.mail to limit the Console messages to Mail.

  5. Use the Filter field to find the specific email account that has problems. For example, if there's a problem connecting to Gmail, enter gmail.com in the Filter field. If there's a connection problem when sending mail, enter smtp in the Filter field to only show logs concerning sending email.

Use the Mail logs to find the type of problem, such as rejected passwords, rejected connections, or down servers. After you locate the problem, use Mail to make corrections to the Account settings and run the Connection Doctor again for a quick test. The most common problems are the wrong account name or password, connecting to the wrong server, the wrong port number, or using the wrong form of authentication.

Use the logs to check all the above against the information your email provider gave you to set up your email client. If you still have problems, copy the Mail logs that show the problem and ask your email provider to review them and provide assistance.