Document module hooks

I've included a new .api. file as a best practice for doing this. hook_mailhandler arguments are unclear at all. I think there must be additional backgroud.

Actually, the email manual retrieval operation and cron follow different paths, so there must be a problem with this hook. The 'ui' retrieve method is loosing some of the arguments, one of the is the $msg_number that is passed to this hook.