Skip to content

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.

It also provides a Mail class that is responsible for creating and formatting emails. Most of the time, you'll be using the Mail class to create and send emails.

It also provides a mailer() method that is responsible for creating and formatting emails. Most of the time, you'll be using the mailer() method to create and send 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:

ParamUse case
hostHostname for your mail server
portPort for your mail server
securityAny encryption supported by PHPMailer
authAuth for your mail server

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:

ParamUse case
debugEnable or disable debug mode. Supported values are 'SERVER', false or any value supported by PHPMailer's SMTPDebug config
defaultsThis config is used to set default values for the recipientEmail, recipientName, senderEmail, senderName, replyToName, and replyToEmail of your emails.
keepAliveThis config is used to keep the connection to your mail server alive. This is useful if you are sending multiple emails. It takes in a boolean.
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.

To send your first mail, you'll need to create a new instance of the Leaf\Mail class. It takes in an array used to create your email:

$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();

You can also use the create() method to create your mail:

$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();

To send your first mail, you'll need to call the create() method returned from mailer(). It takes in an array used to create your email:

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:

ParamUse case
subjectThe subject of your email
bodyThe body of your email
recipientEmailThe email of the person you're sending the mail to
recipientNameThe name of the person you're sending the mail to
senderNameThe name of the person sending the mail
senderEmailThe email of the person sending the mail
replyToNameAdd a name for your "Reply-To" address
replyToEmailAdd a "Reply-To" address
ccThe email of the person you want to carbon copy
bccThe email of the person you want to blank carbon copy
isHTMLA boolean value that determines if your mail is HTML or not
altBodyThis body can be read by mail clients that do not have HTML email capability such as mutt & Eudora. Clients that can read HTML will view the normal Body

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();
}
Leaf Mail has loaded