The mail() function doesn't often fail. I've never seen it happen.
That doesn't mean that everything you send via the mail() command will get through to its intended recipient. There are any number of thing that could go wrong down the line.
- the email address could be wrong
- the local mail processor could be badly configured
- the recipient's mail processor could be down or badly configured
- the recipient's mail processor could be unreachable
- the recipient's mailbox could be full
- the recipient's mail processor could delete your message as spam
- ... and tons of other things
These issues all arise after the mail() command has completed, so it can't know about them. All the mail command can tell you is that it has passed the mail on to the next link in the chain. To quote the manual " It is important to note that just because the mail was accepted for delivery, it does NOT mean the mail will actually reach the intended destination."
You say that mail() is always returning FALSE. Are the mails actually getting through? If the mails aren't, and mail is returning FALSE, it's having trouble passing the mail on to the MTA
(mail transport agent). Is your MTA up and running - something like sendmail or postfix? Is your php.ini correctly configured to find it? Are your variable correctly formatted?
I know you're looking for some way to have mail() tell you what the problem is, but I don't know how to do that, so I guess I'm just suggesting things to check.
Try a simple example. If that works, the problem's in your code, if it doesn't ,the problem's in your setup.
mail("you@yourdomain.com", "Test Subject", "Hello World");