How to Debug and Fix PHP Mail in Localhost
Time to read: 3 minutes
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.
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.
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:
$ sudo vi /etc/postfix/main.cf
Once open, you’re going to check to make sure that the following 4 variables are defined as follows:
compatibility_level = 2
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.
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:
$to = "YOUR EMAIL";
$subject = "Test Mail";
$message = "This is a test email";
echo mail($to, $subject, $message);
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:
$ php mail.php
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.)
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:
From APIs to SDKs to sample apps
API reference documentation, SDKs, helper libraries, quickstarts, and tutorials for your language and platform.
The latest ebooks, industry reports, and webinars
Learn from customer engagement experts to improve your own communication.
Twilio's developer community hub
Best practices, code samples, and inspiration to build communications and digital engagement experiences.