How to Debug and Fix PHP Mail in Localhost

How to Debug and Fix PHP Mail in Localhost

Sending emails in your local environment using PHP’s mail() function should be straightforward. The function is 20-years-old and one of the most integral parts of any web application; email.

If you’re not familiar with mail(), it’s a single function that only requires three arguments—a recipient, subject, and message—to deliver an email via one line of code. Sounds simple, right?

Well, if you’ve actually tried to use the function in your local environment, you know firsthand that it’s not always that easy. You’re probably reading this tutorial because you’ve experienced the mail() function not working out of the box yourself. Maybe you’re even one of the 343K viewers of this unresolved, 5-year-old Stack Overflow ticket.

So why isn’t my PHP mail function sending any mail?

The truth is, there could be a number of reasons why your emails aren’t arriving in inboxes. However, I’ve found that most of those reasons are related to Postfix not being configured properly. Postfix is a fast, secure, open-source mail transfer agent that routes and delivers emails. Postfix follows the SMTP protocol and runs on virtually every Unix-like operating system, including macOS.

Because of its wide adoption, Postfix actually comes pre-installed on most non-Windows based computers. So why isn’t your PHP mail function working? It’s most likely because Postfix isn’t configured.

How do you configure Postfix?

Our test to see if Postfix is configured correctly actually begins with testing to see if it’s installed. In your terminal, run the following command:

Any errors outputted during this time may provide some insight as to what’s not working. However, if you get a response that indicates it’s installed, move on to the next section. If it hasn’t been installed, check out the Postfix documentation or contact your host for installation instructions.

Postfix has some minimum requirements that must be met before emails will send correctly.

The first thing you need to do is modify your local Postfix configuration. You can load an editor directly from your terminal by running the following command:

Once open, you’re going to check to make sure that the following 4 variables are defined as follows:

That’s it! Save these changes and restart Postfix using sudo postfix reload.

NOTE: In my experience, the most important of these variables is myhostname. Without this variable being set, your local environment cannot assign a default location to send the email from. This value can be a real domain or something arbitrary just as in the example above.

Testing Postfix and PHP mail()

To test that Postfix is working and subsequently PHP mail(), let’s create a simple script to run. In your favorite integrated development environment (IDE), create a file called mail.php and add the following code:

Be sure to replace the $to variable with your actual email address. In your terminal, run the program using the following command and check your email:

Additional Troubleshooting

If you've tested Postfix and your PHP mail() function still isn't sending mail, here are a few other issues to consider:

• Missing required parameters (Check the official PHP mail documentation to verify.)
• Typos with your recipient email address
• Needing to set up an SMTP relay (This guide can help you set up Postfix to use SendGrid as a relay host.)

Conclusion

Now that you have completed this tutorial, you have the knowledge of setting up Postfix, the inconsistencies of mail(), and how to write a simple email script to send a test email in PHP.

If by chance you are still running into issues, feel free to reach out.

Marcus Battle is Twilio’s PHP Developer of technical content where he prompts and rallies PHP developers to build the future of communications. He can be reached via:

• Email: mbattle@twilio.com
• Twitter: @themarcusbattle
• Github: https://github.com/themarcusbattle