Sending email using the Mailgun PHP API

Why should I care about transactional email?

We’re going to kick off this how-to by saying that transactional email is everywhere, and it’s important we get it right. Not getting email to work properly could mean losing revenue for your business and just overall creates an unpleasant experience for customers.

As a developer, you’re always looking to find the most simple (time-efficient) and powerful way to solve a problem. You often achieve this by fulfilling two conditions:

1. Using external libraries that apply to your solution.

2. Designing scalable applications.

No need to explain the first condition – you wouldn’t start to write an OS before coding an application, right? Throughout the post, we’ll look at how to use pre-written packages to send email. But now, on to my second point: read on. 

For scalable design, this is where you look for services like Mailgun. You can expect a feature-rich solution that meets requirements for high-volume email sending.

If you care about delivery (and you should), Mailgun offers high reliability as it’s designed to handle transactional email very well. You can set up multiple domains and choose if you want to share IPs or build your own reputation. To protect your email headers, Mailgun requires DKIM and SPF be added to the account, and that they pass their checks at the authentication and alignment level. All of these things work together to help you with email delivery.

Now to the good stuff: setting up a PHP wrapper script for Mailgun. First, we’ll use the package manager and then see examples of how to apply it.

Setting up your environment

PEAR is a community driven initiative that lets us reuse PHP code components, while the dependent code is also added and maintained.

First, you will need PHP, and the package manager to continue. They’re best installed by Debian Advanced Package Manager (APT) if you’re using Linux.

Although PEAR is an older solution, it’s still widely used and it’s short for PHP Extension and Application Repository. Based on the installed PHP version, you probably already have PEAR available. You can check by running pear command without arguments. If you receive a warning that your system doesn’t have it, just run: sudo apt install php-pear. Now, we’re ready to install third-party PHP code with PEAR.

If you follow this article by coding along, this is the point where you should open your Mailgun account to have access to the API. If you get stuck, just check these getting started bits of advice.

Setting up the project

The steps with PEAR apply in the following way:

1. Installing project dependencies and including the packages by requiring the main class or the vendor/autoloader.php script

2. Provide API related variables

3. Instantiating the Mail class/client

4. Make function call to send the email(s)

Simple, right?

Using PEAR

Step 1: Install the project dependencies

We can install the Mail package by typing sudo pear install Mail. After it’s finished installing, the next step is to include that in a script file:

require_once "Mail.php";

Save yourself some time and do as our boilerplate suggests, then provide the API specific variables. 

Step 2: Provide input variables

If you head to your API dashboard, you can find these necessary pieces of information under the domain tab:

We need the host, account user and password variables, and the port to use:

We use SMTP connection to send email through our Mailgun account.

Step 3: Instantiate the client

We gather the above parameters into an array and instantiate the Mail class with this:

Step 4: Make a call to the client

The final step is to call the send() method of the Mail class and we are good to go:

Here, the $to variable holds the value for the recipient address, while the $headers variable is an array, containing additional fields for delivery.

At this point, you may want to check out the full final code:

You can download the full source code here.

Moving on, if you set up everything, you can try to run the script: php mailer.php.

You run it, and receive an ugly error stack trace! Examine it closely:

PHP Fatal error: Uncaught Error: Class 'Net_SMTP' not found in /usr/share/php/Mail/smtp>php:366.

This means that we forgot to add another project dependency that’s necessary to use PEAR Mail. Run sudo pear install Net_SMTP and try again!

The output is:

Message sent successfully!

If you followed along, then your message should have arrived to the specified mailbox, and I’m silent clapping for you. Bravo! 

Conclusion

We saw the sample script to get started using Mailgun with the PEAR package manager, and we created PHP scripts to send an email with SMTP and the HTTP API. But there are other options you could use if PEAR isn’t your go-to choice. You could actually replicate the same outcome using Composer, and Mailgun has gone into detail about this previously on the blog. 

And of course, if you wish to improve your skills with PHP, these are a few of my favorite resources that I would recommend for sending email with PHP and dealing with email HTML in general.