Leaf Mail #

Mailing in PHP apps has always been seen as a daunting task. Leaf Mail provides a simple, straightforward and efficient email API that is built on the widely used PHPMailer Library component.

With Leaf Mail, you can easily send emails using various drivers and services such as SMTP, Mailgun, SendGrid, Amazon SES, and sendmail. This flexibility enables you to swiftly begin sending emails through a preferred local or cloud-based service.

Installation #

You can install leaf mail using the leaf cli:

leaf install mail

or with composer:

composer require leafs/mail

Setting Up #

Leaf Mail provides a Mailer class that is responsible for validating and sending emails. This class handles the connection to your mail server, the configuration for how to send your emails and the actual sending of emails.

Note that you need to setup the connection to your mail server using the Leaf\Mail\Mailer class before sending your emails.

Mail Server Connection #

The Leaf\Mail\Mailer class is responsible for connecting to your mail server and handling the sending emails. It provides a connect() method that you can use to connect to your mail server.

The connect() method takes in an array of configuration options that you can use to configure your mail server connection. The configuration options are:

Gmail connection example #

Gmail is one of the most popular mail servers. Unfortunately, a connection with your email and password is no longer supported, so you will need to use OAuth. You will need to add an OAuth provider like league/oauth2-google to your project.

leaf install league/oauth2-google

# or with composer

composer require league/oauth2-google

From there you can create your connection like this:

use Leaf\Mail\Mailer;
use League\OAuth2\Client\Provider\Google;
use PHPMailer\PHPMailer\OAuth;
use PHPMailer\PHPMailer\PHPMailer;

...

Mailer::connect([
  'host' => 'smtp.gmail.com',
  'port' => 465,
  'security' => PHPMailer::ENCRYPTION_SMTPS,
  'auth' => new OAuth(
    [
      'userName' => 'mail@gmail.com',
      'clientSecret' => 'CLIENT_SECRET',
      'clientId' => 'CLIENT_ID',
      'refreshToken' => 'GMAIL_REFRESH_TOKEN',
      'provider' => new Google(
        [
          'clientId' => 'CLIENT_ID',
          'clientSecret' => 'CLIENT_SECRET',
        ]
      ),
    ]
  )
]);

SMTP connection example #

The example above uses OAuth, however, some mail servers also support using a username/password for connections. Here's an example of connecting to Mailtrap using SMTP:

use Leaf\Mail\Mailer;
use PHPMailer\PHPMailer\PHPMailer;

...

Mailer::connect([
  'host' => 'smtp.mailtrap.io',
  'port' => 2525,
  'security' => PHPMailer::ENCRYPTION_STARTTLS,
  'auth' => [
    'username' => 'MAILTRAP_USERNAME',
    'password' => 'MAILTRAP_PASSWORD'
  ]
]);

Mailer config #

The Mailer class provides a config() method that you can use to configure your mail server connection. The configuration options are:

Mailer::config([
  'keepAlive' => true,
  'debug' => 'SERVER',
  'defaults' => [
    'recipientEmail' => 'name@mail.com',
    'recipientName' => 'First Last',
    'senderName' => 'Leaf Mail',
    'senderEmail' => 'mychi@leafphp.dev',
  ],
]);

Setting your defaults allows you to send your mails without having to configure sender/receiver mails for every mail.

Your first mail #

Now that we've gotten all the annoying config out of the way, all that's left is the easy part: sending your mails.

$mail = new \Leaf\Mail([
  'subject' => 'Leaf Mail Test',
  'body' => 'This is a test mail from Leaf Mail using gmail',
  
  // next couple of lines can be skipped if you
  // set defaults in the Mailer config
  'recipientEmail' => 'name@mail.com',
  'recipientName' => 'First Last',
  'senderName' => 'Leaf Mail',
  'senderEmail' => 'mychi@leafphp.dev',
]);

// Send your mail
$mail->send();

$mail = \Leaf\Mail::create([
  'subject' => 'Leaf Mail Test',
  'body' => 'This is a test mail from Leaf Mail using gmail',
  
  // next couple of lines can be skipped if you
  // set defaults in the Mailer config
  'recipientEmail' => 'name@mail.com',
  'recipientName' => 'First Last',
  'senderName' => 'Leaf Mail',
  'senderEmail' => 'mychi@leafphp.dev',
]);

// Send your mail
$mail->send();

mailer()
  ->create([
    'subject' => 'Leaf Mail Test',
    'body' => 'This is a test mail from Leaf Mail using gmail',
    
    // next couple of lines can be skipped if you
    // set defaults in the Mailer config
    'recipientEmail' => 'name@mail.com',
    'recipientName' => 'First Last',
    'senderName' => 'Leaf Mail',
    'senderEmail' => 'mychi@leafphp.dev',
  ])
  ->send();

This is a full list of the parameters you can use to create your mail:

Adding Attachments #

You can add attachments to your mail using the attach() method. It takes in an array of attachment data or just a string containing a single attachment. The attachment data is an array containing the following keys:

$mail = new \Leaf\Mail([
  'subject' => 'Leaf Mail Test',
  'body' => 'This is a test mail from Leaf Mail using gmail',
]);

$mail->attach('./attachment.txt');
$mail->attach([
  './file1.txt',
  './file2.txt'
]);

$mail->send();

mailer()
  ->create([
    'subject' => 'Leaf Mail Test',
    'body' => 'This is a test mail from Leaf Mail using gmail',
  ])
  ->attach('./attachment.txt')
  ->attach([
    './file1.txt',
    './file2.txt'
  ])
  ->send();

Error handling #

In order not to flood your application with logs and errors, Leaf Mail gathers all errors thrown by the mail server, and saves them internally. You can return all errors with $mail->errors()

if (!$mail->send(...)) {
  return $mail->errors();
}