CakePHP: Send transactional emails using Mailgun

Sending email is a basic need of every application. Examples of transactional emails are Receipts, Password Resets, Signup Confirmation Emails etc.

Why should we use transactional email service providers?

There is another options to send these type of emails — use email service providers. Now, the question is, why should we use transactional email service providers such as Mailgun or SparkPost or Mandrill?

• Speed and Deliverability
• Limitation of emails e.g. Gmail has limit to send daily email via SMTP
• Higher probability of inbox penetration
• Reports — different reports of your emails

In CakePHP, there is a in-built functionality to send emails using different options like SMTP or PHP’s mail library. See my article for more details.

After reviewing several transactional email service providers, I have selected Mailgun and created a plugin to easily integrate it with CakePHP. Now, let’s start with implementation.

Installation

Install the plugin into your CakePHP application using composer like,

composer require narendravaghela/cakephp-mailgun

After installing, load the plugin into your application like,

Plugin::load(‘MailgunEmail’);

The basic installation is now completed.

Account setup & configuration

First, create your account at Mailgun. After signup, get your API key from account settings. You also need to setup your sending domain there as well. It is quite easy — see their doc here.

Now, we need to configure our CakePHP application to use Mailgun as email sending service. For that, set your Mailgun credentials in EmailTransport settings in app.php.

'EmailTransport' => [
  'mailgun' => [
      'className' => 'MailgunEmail.Mailgun',
      'apiKey' => 'key-123456789123456789', // your api key
      'domain' => 'test.mailgun.org' // your sending domain
  ]
]

The above settings will be used in Mailgun API configuration. Once you setup the email transport, create a new email delivery profile. Open your app.php and under Email settings, set the following.

'Email' => [
    'default' => [
        'transport' => 'default',
        'from' => 'you@localhost',
        //'charset' => 'utf-8',
        //'headerCharset' => 'utf-8',
    ],
    'mailgun' => [
        'transport' => 'mailgun'
    ]
]

Now, our application is configured to use Mailgun as email sending service.

Send email

Sending email using above configuration is very easy. Just create your Email object as usual and pass mailgun as argument.

$email = new Email(‘mailgun’);

That is it. Now it will use Mailgun to send your emails. Let’s see some examples.

Send a simple email

Below is a very simple example of sending email.

$email = new Email(‘mailgun’);
$email->from([‘me@example.com’ => ‘My Site’])
    ->to(‘you@example.com’)
    ->subject(‘About’)
    ->send(‘My message’);

Send email with custom headers

Mailgun supports additional parameters. You can set them using addHeaders() function. See here for list of additional parameters.

$email = new Email(‘mailgun’);
$result = $email->from([‘foo@example.com’ => ‘Example Site’])
    ->to(‘bar@example.com’)
    ->subject(‘Welcome to CakePHP’)
    ->addHeaders([‘o:tag’ => ‘testing’])
    ->addHeaders([‘o:deliverytime’ => strtotime(‘+1 Min’)])
    ->addHeaders([‘v:my-custom-data’ => json_encode([‘foo’ => ‘bar’])])
    ->send(‘Your email content here’);

Send email with template and attachments

$email = new Email('mailgun');
$result = $email->from(['foo@example.com' => 'Example Site'])
  ->to('bar@example.com')
  ->subject('Welcome to CakePHP')
  ->template('welcome')
  ->viewVars(['foo' => 'Bar'])
  ->emailFormat('both')
  ->addHeaders(['o:tag' => 'testing'])
  ->addHeaders(['o:deliverytime' => strtotime('+1 Min')])
  ->addHeaders(['v:my-custom-data' => json_encode(['foo' => 'bar'])])
  ->readReceipt('admin@example.com')
  ->returnPath('bounce@example.com')
  ->attachments([
      'cake_icon1.png' => Configure::read('App.imageBaseUrl') . 'cake.icon.png',
      'cake_icon2.png' => ['file' => Configure::read('App.imageBaseUrl') . 'cake.icon.png'],
      WWW_ROOT . 'favicon.ico'
  ])
  ->send('Your email content here');

That is it. If you have a problem with this plugin or found any bug, please open an issue on GitHub.