The Mailer Service

Configuration

Once you have selected a mail service provider, you can configure your host, username, and password in your environment variables (or .env file):

For more advanced configuration, you can override the mail configuration values in your site sprinkle configuration :

'mail'    => [
    'mailer'          => 'smtp', // Set to one of 'smtp', 'mail', 'qmail', 'sendmail'
    'host'            => getenv('SMTP_HOST') ?: null,
    'port'            => 587,
    'auth'            => true,
    'secure'          => 'tls', // Enable TLS encryption. Set to `tls`, `ssl` or `false` (to disabled)
    'username'        => getenv('SMTP_USER') ?: null,
    'password'        => getenv('SMTP_PASSWORD') ?: null,
    'smtp_debug'      => 4,
    'message_options' => [
        'CharSet'   => 'UTF-8',
        'isHtml'    => true,
        'Timeout'   => 15,
    ],
],

The smtp_debug setting determines the verbosity of logs that are sent to your mail.log:

Creating messages

To create a new email message, create a new template in your Sprinkle's templates/mail/ directory:

confirm-owl.html.twig

{% block subject %}
    Please confirm your owl {{new_owl.name}}
{% endblock %}

{% block body %}
<p>
    Dear {{user.first_name}},
</p>
<p>
    Your owl has been accepted.  Please use the link to verify your relationship with this owl:
    <a href="{{site.uri.public}}/account/owls/{{new_owl.id}}/verify?token={{new_owl.token}}">
        {{site.uri.public}}/account/owls/{{new_owl.id}}/verify?token={{new_owl.token}}
    </a>
</p>
<p>
    With regards,<br>
    The {{site.title}} Team
</p>
{% endblock %}

You'll notice that the message contains two separate blocks for the subject and body of your message.

To load your message in your controllers, create a new TwigMailMessage object:

use UserFrosting\Sprinkle\Core\Mail\EmailRecipient;
use UserFrosting\Sprinkle\Core\Mail\TwigMailMessage;

...

$message = new TwigMailMessage($this->ci->view, "mail/confirm-owl.html.twig");

Senders, recipients, and customized content

To set the From field for your message, simply call the from method on your message, passing in an array containing email, name, and optionally, reply_email and reply_name values:

$message->from([
    'email' => '[email protected]',
    'name' => 'The Owl Fancy Team'
]);

If you don't set reply_email and reply_name, email and name will be used.

You can add one or more recipients by creating a new EmailRecipient object and passing it into the addEmailRecipient method:

$message->addEmailRecipient(
    new EmailRecipient($user->email, $user->full_name)
);

You can call the cc and bcc methods on your new EmailRecipient object to add CC and BCC fields for the recipient.

$recipient = new EmailRecipient($user->email, $user->full_name);
$recipient->cc('[email protected]', 'Owl Lover');
$recipient->bcc('[email protected]', 'Hawk Fancier');
$message->addEmailRecipient($recipient);

You can set recipient-specific Twig parameters by passing in an array to the last parameter of the EmailRecipient constructor:

$message->addEmailRecipient(
    new EmailRecipient($user1->email, $user1->full_name, [
        'new_owl' => $user1->newOwl
    ])
);
$message->addEmailRecipient(
    new EmailRecipient($user2->email, $user2->full_name, [
        'new_owl' => $user2->newOwl
    ])
);

Alternatively, you can use the addParams method to pass in common Twig parameters for all recipients:

$message->addParams([
    'time' => Carbon::now()->format('Y-m-d H:i:s')
]);

All methods for TwigMailMessage can be fluently chained together into a single statement.

Sending your message

To actually send your message, pass your TwigMailMessage into the sendDistinct method of your mailer service:

$this->ci->mailer->sendDistinct($message);

sendDistinct will send a separate email to each recipient, passing in any custom data that was defined in the EmailRecipient constructor. If you are trying to send a single message to a list of recipients, just use send instead. Note that in the case of send, any recipient-specific Twig parameters will be ignored.

Error handling

If a problem arises while attempting to send a message, a phpmailerException will be thrown. By default, this exception is caught by the Error/Handler/PhpMailerExceptionHandler (defined in the core Sprinkle). Of course, you can define your own exception handler instead.