Writing a Send Email Function

No matter what the specific use case of sending an email, there are a couple of steps that need to be taken and pieces of Mail Core that need to be understood before you actually send an email.

Inject Mailer

The first step is relatively easy, in your email sending function, you must inject the mailer in order to begin writing (and sending) your email message.

$emailMessage = $this->inject('mailer');

Essentially this is the same thing as creating a variable as an instance of a class. All future functions changing various aspects of the email message will be called using this variable.

Functions To Call

While no two emails are exactly alike, there are many aspects of email sending that are the same or similar throughout each use of the email. Mail Core relies heavily upon PhpMailer, which is a common way of sending emails directly with php. However, Mail Core, adds several functions that abstract a lot of the functionality of Mail Core to make the programming of sending the emails easier upon the developer.

Basic Functions

There are several basic functions you need to use. Some of these are added by Mail Core itself, and others are a part of PhpMailer. But using these are the only things you need to actually send a message.

message(values)

This function returns a Message Instance. This should be used instead of Message::__construct() as this method also handles dependency injection. This is what actually creates the message.

Params

  • values Array. This is an associative array to set all the attributes of the Message Class. Most often it is used to set the subject attribute. Default is an empty array.

Example

$emailMessage->message(['subject' => 'You have been clocked out']);
template(content, data, isHtml, renderer)

Load body contents for the email from a rendered template. This pulls a template file. To understand how to build a template file, see Writing A Template. Most of the time this will be used instead of directly setting the body attribute using the set function.

If you do not desire to use a template to render your body, you can use the set function to set the attribute 'body' to whatever value you desire.

Params

  • content String. This is the name of the file containing the template. (how to format the template is shown in example). Default is null

  • data Array. This is an associative array of variables to insert into the template. Default is null.

  • isHtml Boolean. This is whether or not the content is HTML or not. Default is false.

  • renderer String. This is the renderer to use. Current options are PhpRenderer or HandlebarsRender. Defaults to PhpRenderer.

Example

$emailMessage->template('clockOutMessage.php', ['name' => $name,
'time' => $time]);
setConfigFrom(name)

This function is required. It sets the default from name and address based on config. Due to issues with phishing emails commonly being sent out via phpMailer, a lot of emails would be marked as phishing, and therefore never reach their destination. To fix this, we use setConfigFrom to change the name of the sender, but leave the sender email address to match the domain it was sent from, which causes it to pass SPF validation. (If you wish to send the email without a overriding the from name, please use this function without a name parameter, which will set the sender information using default values).

Within our apps, this is used commonly with addReplyTo. Both of these functions together make the end user feel that it is actually sent from the person's email (as hitting reply sends to the user) without making it look like a spoofed phishing email (which it isn't).

Params

  • name String. Name to use for the sender, if unset it uses the default name from the config in app.php (mail-core.sender.name, which you set in the Setup phase of this documentation). Default is null.

Example

Here are the two ways you can use this function:

//override the sender name to come from John Smith
$emailMessage->setConfigFrom('John Smith');

//leave default sender name (from our example Message Center Notifications)
$emailMessage->setConfigFrom();
addAddress(email, name)

The purpose of this function is to add a recipient of the email. The name and address are added to the "To" section of the email.

Params

  • email String. This is the email that you are sending the email to. This is required and must be formatted properly as an email. Default is null.

  • name String. This is the name of the person you are sending the email to. This is not required. Default is null.

Example

$emailMessage->addAddress('infoadmin95@gmail.com', 'Informatics Admin');
addReplyTo(email, name)

The purpose of this function is to change who any reply email is sent to. Ordinarily a reply email would be sent to whoever the email was from, but since we have changed the sender email for SPF validation to a default email, we need a way to send the reply to the actual sender of the email through the FW system. That is done through the addReplyTo. The name and address are added to the "Reply-To" section of the email.

This function should be used in tandem with setConfigFrom (if you define a name parameter). If one is used, the other should be used.

Params

  • email String. This is the email that the recipient will reply to. This is required and must be formatted properly as an email. Default is null.

  • name String. This is the name of the person the recipient will reply to. This is not required. Default is null.

Example

$emailMessage->addReplyTo('infoadmin95@gmail.com', 'Informatics Admin');
send(exceptions)

This function sends the email message, and gives you more control over how to deal with errors in the sending of the email.

Params

  • exceptions Boolean. If true, it send throws an exception if the message fails to send, otherwise it logs the error. Note: this should not be set to true if the email is sent as a "side effect" of another action. Default is false.

Example

$emailMessage->send();

Advanced Functions

Here are some functions you may come across or use, but these are used very rarely. Of course, this is not an exhaustive list of all the functions you can use with PhpMailer, but these are the ones that are important enough to highlight. For a full list of all PhpMailer functions there are, please visit the PhpMailer Documentation. Here are the few functions selected to go over here:

addCC(email, name)

The purpose of this function is to add a recipient of the email. The name and address are added to the "CC" section of the email.

Params

  • email String. This is the email that you are sending the email to. This is required and must be formatted properly as an email. Default is null.

  • name String. This is the name of the person you are sending the email to. This is not required. Default is null.

Example

$emailMessage->addCC('infoadmin95@gmail.com', 'Informatics Admin');
addBCC(email, name)

The purpose of this function is to add a recipient of the email. The name and address are added to the "BCC" section of the email.

Params

  • email String. This is the email that you are sending the email to. This is required and must be formatted properly as an email. Default is null.

  • name String. This is the name of the person you are sending the email to. This is not required. Default is null.

Example

$emailMessage->addBCC('infoadmin95@gmail.com', 'Informatics Admin');
get(key)

This function gets a value from the internal PhpMailer instance. If there is no key found, it will throw an exception. While this may be helpful to know, this function has not been used yet external to Mail Core itself.

Params

  • key String. Key to get.

Example

$emailMessage->get('subject');
set(key, value)

This function directly sets a value in the internal PhpMailer instance. This is used VERY infrequently external to Mail Core, but it can be used to circumvent using a template by setting the body value directly.

Params

  • key String|Array. Key to set. If it is an associative array, it sets all the key value pairs within the array. Required.

  • value Mixed. This is the value you will set the key to (if the key is not an array). This value is required if the key is not an array. The data type depends on the key you are setting. Default is null.

Example

$emailMessage->set('body', 'To whom it may concern...');

Full Integrated Example

While each of the functions had a code example, it can be helpful to see all of it incorporated into an example, as suggested in the Introduction, each of these integrated examples shows the different aspects of sending the same email.

//in this example, the recipients are passed in to the function. Those will often be gotten from a
//    notifications table, but for the course of this example, that is unnecessary to display

public function sendTestEmail($recipients, $name, $note, $color) {
    $this->auth();

    //make the subject
    $subject = "Your car has been totaled";

    //get the sender information
    $userFirst = $this->user->get('namePref') ?: $this->user->get('nameFirst');
    $userLast = $this->user->get('nameLast');
    $senderName = "$userFirst $userLast";
    $senderEmail = $this->user->get('email');

    //create the message
    $message = $this->inject('mailer')
            ->message(['subject' => $subject])
            ->template("car-totaled.php", [
                "name" => $name,
                "note" => $note,
                "color" => $color,
                "sender" => $senderName
            ], true)
            ->addConfigFrom($senderName);

    //add reply to if there is an email to send it to
    if ($senderEmail) {
        $message->addReplyTo($senderEmail, $senderName);
    }

    //add addresses for each of the recipients
    foreach ($recipients as $receiver) {
        $message->addAddress($receiver['email'], $receiver['name']);
    }

    //send message
    $message->send();
}