Using Apple Mail's Troubleshooting Tools

A frustrated woman using a Mac notebook computer.

Rafal Rodzoch/Caiaimage/Getty Images

​Apple Mail is very straightforward to set up and use. Along with the convenient guides that step you through the process for creating accounts, Apple also provides a few troubleshooting guides designed to help you when something isn't working.

The three main assistants for diagnosing problems are the Activity window, the Connection Doctor, and Mail logs.

Using Apple Mail's Activity Window

Mac mail on laptop screen


The Activity window, available by selecting Window, Activity from the Apple Mail menu bar, displays the status when sending or receiving mail for each mail account you have. It's a quick way to see what may be going on, such as an SMTP (Simple Mail Transfer Protocol) server refusing connections, a wrong password, or simple timeouts because the mail server can't be reached.

The Activity window has changed over time, with earlier versions of the Mail app actually having 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 any method for correcting problems, but its status messages will alert you when something is going wrong with your mail service and usually help you figure out what it is. If the Activity window shows problems with one or more of your Mail accounts, you'll want to try the two additional troubleshooting aids provided by Apple.

Using Apple Mail's Connection Doctor

Apple Mail's Connection Doctor in use screenshot


Apple's Connection Doctor can help you diagnose problems you're having with Mail.

The Connection Doctor will confirm that you're connected to the internet and then check each mail account to ensure you can connect to receive mail, as well as connect to send mail. The status for each account is then displayed in the Connection Doctor window. If you're unable to connect to the internet, the Connection Doctor will offer to run Network Diagnostics to track down the cause of the problem.

Most Mail issues are likely to be account related rather than internet connection related, however. To help 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.

Running Connection Doctor

  1. Select Connection Doctor from the Window menu of the Mail program.
  2. Connection Doctor will automatically start the checking process and display the results for each account. Connection Doctor first checks each account's ability to receive mail and then checks each account's ability to send mail, so there will be two status listings for each mail account.
  3. Any account marked in red has some type of connection issue. Connection Doctor will include a brief summary of the issue, such as incorrect account name or password. To find out more about the account issues, you'll want to have the Connection Doctor display the details (logs) of each connection.

View Log Details in the Connection Doctor

  1. In the Connection Doctor window, click the 'Show Detail' button.
  2. A tray will slide out from the bottom of the window. When they're available, this tray will display the contents of the logs. Click the 'Check Again" button to rerun the Connection Doctor and display the logs in the tray.

You can scroll through the logs to find any errors and see a more detailed reason for any problems. The one problem with the detail display in the Connection Doctor is that the text can't be searched, at least from within the Connection Doctor window. If you have multiple accounts, scrolling through the logs can be cumbersome. You could, of course, copy/paste the logs to a text editor and then try to search for specific account data, but there is another option: the Mail logs themselves, which your system keeps tabs on.

Using Console to Review Mail Logs

Mail Connection Doctor screenshot
The keep track of connection activities, place a check mark in the Log Connection Activity box.


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. Since the Activity window is real-time, if you glance away or even blink, you may miss seeing a connection issue. The Mail logs, on the other hand, keep a record of the connection process that you can review at your leisure.

Enabling Mail Logs (OS X Mountain Lion and Earlier)

Apple includes an AppleScript to turn Mail logging on. Once it's turned on, the Console logs will keep track of your Mail logs until you quit the Mail application. If you want to keep Mail logging active, you'll have to re-run the script before each time you launch Mail.

To Turn Mail Logging On

  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 top left corner.
  5. If a dialog box opens, asking if you wish to run the script, click Run.
  6. Next, a dialog box will open, asking if you wish to 'Enable socket logging for checking or sending mail. Quit Mail to turn logging off.' Click the Both button.
  7. Logging will be enabled, and Mail will launch.

Viewing Mail Logs

Mail logs are written as Console messages that can be displayed in Apple's Console application. Console allows you to view the various logs your Mac keeps.

  1. Launch Console, located at /Applications/Utilities/.
  2. In the Console window, expand the Database Searches area in the left-hand pane.
  3. Select the Console Messages entry.
  4. The right-hand pane will now display all messages written to the Console. Mail messages will contain the sender ID You can filter out all of the other Console messages by entering into the Filter field in the top right-hand corner of the Console window. You can also use the Filter field to find just the specific email account that's having problems. For instance, if you're having problems connecting to Gmail, try entering '' (without the quotes) in the Filter field. If you're only having a connection problem when sending mail, try entering 'smtp' (without the quotes) in the Filter field to only show logs when sending email.

Enabling Mail Logs (OS X Mavericks and Later)

  1. Open the Connection Doctor window in mail by selecting Window, Connection Doctor.
  2. Place a checkmark in the box labeled Log Connection Activity.

View Mail Logs OS X Mavericks and later

In earlier versions of the Mac OS, you would use the Console to view Mail logs. As of OS X Mavericks, you can bypass the Console app and view the logs gathered with any text editor, including the Console if you wish.

  1. In Mail, open the Connection Doctor window and click the Show Logs button.
  2. A Finder window will open displaying the folder containing the Mail logs.
  3. There are individual logs for each Mail account you have set up on your Mac.
  4. Double-click a log to open in TextEdit, or right-click a log and select Open with from the popup menu to open the log in the app of your choice. 

You can now use the Mail logs to find the type of problem you're having, such as passwords being rejected, connections being rejected, or servers down. Once you locate the problem, use Mail to make corrections to the Account settings, then try running the Connection Doctor again for a quick test. The most common problems are 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 of the above against the information your email provider gave you to set up your email client. Finally, if you still have issues, copy the Mail logs showing the problem and ask your email provider to review them and provide assistance.