I'm a slow adopter of upgrades - Apple announced Mac OS X version 10.10 this week, free for current OSX license holders. So it seemed like a good time to upgrade... to 10.8. I'm of the mindset that if everything is working, there's no need to upgrade, until or unless there is a feature that I must have. (Full disclosure: a game I bought wouldn't run on 10.7).
Upgrading to 10.8 went surprisingly smoothly -- all of my critical programs seem to work. But when I updated to 10.8.5, Apple Mail broke. Specifically, I could not check my iCloud account any more. It wouldn't authenticate.
Tried many things, including beating my head against a wall. OK, actually, tried manually configuring, with various settings (didn't work). Tried using an app-specific password for two-step verification (didn't work). Tried manually configuring with using a different client (Thunderbird) using an app-specific password for two-step verification (worked).
On a whim, just to troubleshoot, I turned off Apple Two-Step Verification on my AppleID, and voila, suddenly I could set up Mail. I didn't even have to set it up manually.
So, inexplicably, Apple Mail seems to not work with two-step verification. Go figure.
Once I turned off two-step verification, several other issues I struggled with today resolved themselves as well: Notes synced, iMessages and Mail notifications are now listed in the Notification Center (I did have to go into system prefs and tell them not to display, close out, then go back in and tell them to display to spur it into action), Mail messages now display popup alerts, as do iMessages.
So, hope this helps someone. Pretty much burned half a day on this.