Custom Emails

The emails component is a very powerful content management functionality that allows you to quickly customize a mailable with custom details and variable oriented values.

In order to provide you with a complex crud functionality inside the admin, the emails crud implements the following out of the box:

Admin Interface

Before going deeper, you should know that there's already a section in the admin from where you can manage all your content.

You can find the emails section inside Admin -> Manage Content -> Emails.
Feel free to explore all available options this section offers.

Emails List

How It Works

First of all, let's understand the architecture behind content blocks and their workflow.

The Workflow

Configuration File

The emails component comes bundled with a config/varbox/emails.php config file.

From here you can specify what email types your application contains and what custom variables your emails can make use of.

You should specify a new email type for each mailable your application will use. For each email type, you can create only one email record inside the admin.

You should keep the variables section up to date with all the variables you're using inside all your mailable classes.

Mailable Files

Running the artisan command for generating custom emails, will generate all necessary files for a mailable.The generated files for each email type are:

app/Mail/{YourMailable}.php

This is the custom mailable class. This class extends the Varbox\Mail\Mailable abstract class, which in turn extends the Illuminate\Mail\Mailable class, so you have available any functionality a basic Laravel mailable offers.

With that said, the actual generated mailable class only exposes 3 methods, in order to make your job of creating a mailable easier.

resources/views/emails/{your_mailable}.blade.php

This is the mailable view that will be used to actual render the sent email. The custom emails use the markdown template.

In the majority of the cases, modifying this file won't be necessary, since you can dynamically change your email's content from the admin panel.

Custom Variables

Beside the fact that you can have emails with a customizable subject, content or even an attachment, you can even leverage custom variables to display, for example, a user's name in your email's content.

You should define your custom variables inside the config/varbox/emails.php config file and then, inside the mapVariables() method from your mailable class you should actually provide a value for your variables.

To specify custom variables for your emails' content inside the admin, wrap your variable name in square brackets: [username]

Usage

Let's see the most common things you can do using custom emails.

Create New Mailable

First, you need to define the type of the email inside the config/varbox/emails.php config file.

'types' => [

    'your-mail' => [

        // The mailable class used for sending the email.
        // This gets generated automatically when running 
        // "php artisan varbox:make-mail"
        'class' => 'App\Mail\YourMail',

        // The blade file used for rendering the email.
        // The value will be relative to the "resources/views/" directory.
        'view' => 'emails.your_mail',

        // Array of variables that the respective mail type is allowed to use.
        // You can customize these variables's values inside your mailable class.
        'variables' => [
            'your_variable_one', 'your_variable_two'
        ],
    ],

],

After you've defined your email type, you can generate the mailable files by running the below command. Please note that the command accepts a single argument, which is your email type.

php artisan varbox:make-mail your-mail

That's it! Now you have two files for your newly created email:

Use Custom Variables

Inside your generated mailable class you'll see a method called mapVariables() that by default returns an array of your custom variables that you've setup in your config/varbox/emails.php for that type.

To specify a dynamic value for your custom variables, simply modify that array with the actual values for each of the variables.

/**
 * Return an array containing:
 * - keys: each variable name as defined inside the "config/varbox/emails.php" -> "variables" config option
 * - values: the actual value that the respective variable (key) should be transformed to
 *
 * @return array
 */
protected function mapVariables()
{
    return [
        'username' => $this->user->name,
        'company' => config('app.name'),

   ];
}

After you've defined the dynamic values for your custom variables, you can reference them from inside the admin, when creating or updating an email like so:

Hi [username]

Welcome to our site!

Regards, [company] team

Send A Custom Email

Given that these custom emails the Varbox platform provides finally extend the Laravel's Illuminate\Mail\Mailable class, you can send these emails like you always did inside a Laravel application.

use App\Mail\YourMail;

Mail::to($request->user())->send(new YourMail);

Customize Email Design

In order to change the design of your emails, please follow this Laravel documentation section

Configuration

The emails configuration file is located at config/varbox/emails.php.

For more information on how you can customize the content management components, please read the comments from their configuration files.

Overwrite Bindings

In your projects, you may stumble upon the need to modify the behavior of these classes, in order to fit your needs. Varbox makes this possible via the config/varbox/bindings.php configuration file. In that file, you'll find every customizable class the platform uses.

For more information on how the class binding works, please refer to the Custom Bindings documentation section.

The email classes available for binding overwrites are:

Varbox\Models\Email

Found in config/varbox/bindings.php at models.email_model key.
This class represents the email model.

Varbox\Controllers\EmailsController

Found in config/varbox/bindings.php at controllers.emails_controller key.
This class is used for interactions with the "Admin -> Manage Content -> Emails" section.

Varbox\Requests\EmailRequest

Found in config/varbox/bindings.php at form_requests.email_form_request key.
This class is used for validating any email when creating or updating.

Varbox\Filters\EmailFilter

Found in config/varbox/bindings.php at filters.email_filter key.
This class is used for applying the filtering logic.

Varbox\Sorts\EmailSort

Found in config/varbox/bindings.php at sorts.email_sort key.
This class is used for applying the sorting logic.