beebmx/kirby-courier

Kirby Courier offers a convenient and painless solution for creating emails tailored for your Kirby website.

1.0.3 2024-10-08 19:19 UTC

Requires

• php: ^8.2
• getkirby/composer-installer: ^1.0
• tijsverkoyen/css-to-inline-styles: ^2.0

Requires (Dev)

• getkirby/cli: ^1.5
• getkirby/cms: ^4.3
• laravel/pint: ^1.0
• pestphp/pest: ^2.0
• spatie/ray: ^1.40

MIT

• Fernando Gutierrez

• mail
• email
• courier
• kirby
• kirby-4

README

Kirby Courier

Kirby Courier offers a convenient and painless solution for creating emails tailored for your Kirby website. With Kirby Courier, you can streamline the process of email design and implementation for your site.

Overview

• 1. Installation
• 2. Usage
• 3. Snippets
• 4. Console
• 5. Helper
• 6. Options
• 7. License
• 8. Credits

Installation

Download

Download and copy this repository to /site/plugins/kirby-courier.

Composer

composer require beebmx/kirby-courier

Usage

Kirby Courier comes with two email message types, and you can customize them for your convenience.

Notification message

The Notification message is the easiest way to send an email. You only need to use the Beebmx\KirbyCourier\Notification\Message class in your controller or in your own implementation. Here's an example:

use Beebmx\KirbyCourier\Notification\Message;

(new Message)
    ->to('[e-mail]')
    ->line('Welcome to Kirby Courier')
    ->action('Visit', 'https://beeb.mx')
    ->send()

Formating notification messages

You have several methods to customize your Notification message. Here's an example with all the methods:

use Beebmx\KirbyCourier\Notification\Message;

(new Message)
    ->to('[e-mail]')
    ->greeting('Hello friend!')
    ->line('Welcome to Kirby Courier')
    ->line('You can add more lines before an action')
    ->lines(['Multiple line 01', 'Multiple line 02'])
    ->lineIf($someCondition === true, 'You can add more lines before an action')
    ->linesIf($someCondition === false, ['Line 03', 'Line 04'])
    ->success()         // To set the action button as successful
    ->error()           // To set the action button as an error
    ->action('Action button', 'https://beeb.mx')
    ->line('You can add lines after an action')
    ->salutation('Good bye!')
    ->send()

Warning

You can only add one action per Notification message.

Mail message

The Mail message is the easiest way to send an email if you need to customize all the body of your email, you only need to use the Beebmx\KirbyCourier\Mail\Message class in your controller or in your own implementation. Here's an example:

use Beebmx\KirbyCourier\Mail\Message;

(new Message)
    ->to('[e-mail]')
    ->template('marketing')
    ->send()

Note

It's important that you set a template to display your own customization. Every template should be located in your courier directory.

Formating mail messages

To create your own template for your mail messages, you need to create a file in the default location for Kirby Courier. Here's an example for a marketing message:

/*** /site/template/courier/marketing.php ***/

<?php snippet('courier/message', slots: true) ?>
<?php slot('body') ?>
# Hello Courier

The body of your courier message.

<?php snippet('courier/button', ['url' => ''], slots: true) ?>
Button
<?php endsnippet() ?>

Thanks,
<?= site()->title() ?>
<?php endslot() ?>
<?php endsnippet() ?>

Note

You can add content as markdown and it will be processed by kirbytext.

Message methods

For both Notifications and Mail messages, there are shared methods. Here's an example with all the methods:

use Beebmx\KirbyCourier\Mail\Message;

(new Message)
    ->preset('contact')                     // The preset should be available in your config.php file
    ->from('[e-mail]')
    ->from('[e-mail]', 'Webmaster')  // You can add a name to from address
    ->to('[e-mail]')
    ->to('[e-mail]')                     // You can add multiple recipients (TO)
    ->cc('[e-mail]')
    ->cc('[e-mail]')                     // You can add multiple recipients (CC)
    ->bcc('[e-mail]')
    ->bcc('[e-mail]')                    // You can add multiple recipients (BCC)
    ->replyTo('[e-mail]')
    ->subject('Thank you for your contact request')
    ->theme('dark')                         // The theme should be available in your themes
    ->data(['name' => 'John Doe', 'position' => 'CEO']) // All the data available for the template
    ->attach($page->file('image.jpg'))
    ->attach($page->file('file.pdf'))       // You can add multiple files
    ->attachMany([$page->file('file.pdf'), $page->file('file.jpg')])
    ->render()                              // Returns a Content instance to visualize
    ->send()                                // Trigger to send the email

If you want to previsualize your email, you can do it in any template. Here's an example:

<?= (new Beebmx\KirbyCourier\Mail\Message)
    ->template('marketing')
    ->data(['name' => 'John Doe'])
    ->render()
    ->toHtml() ?>

Note

The render method doesn't trigger any email, and doesn't require any email settings like subject, from or to.

Snippets

For your convenience, Kirby Courier has some snippets to speed up your email building flow. You can add them in your courier template.

Note

You can create your own snippets if you want and apply it to the courier/message snippet. Just be sure to add it in the slot('body').

Button

<?php snippet('courier/button', ['url' => ''], slots: true) ?>
Button
<?php endsnippet() ?>

Panel

<?php snippet('courier/panel', slots: true) ?>
This is a panel
<?php endsnippet() ?>

Table

<?php snippet('courier/table', slots: true) ?>
| Content      | Info          | Currency  |
| ------------ | :-----------: | --------: |
| Content 01   | Centered      | $100      |
| Content 02   | Is centered   | $150      |
<?php endsnippet() ?>

Subcopy

<?php snippet('courier/subcopy', slots: true) ?>
This is a subcopy
<?php endsnippet() ?>

Console

If you are a Kirby CLI user, Kirby Courier also has you covered. The Kirby Courier commands can help you create Mail messages faster or even create your own Courier Theme.

You can create your Mail template with:

$ kirby make:courier <template>
$ kirby courier:make <template>

Note

courier:make is an alias of make:courier

Or may be you want to customize your messages with your own theme with:

$ kirby courier:theme <theme>

Helper

If dealing with namespaces is hard, or you feel confused using the same Message class name, you can simplify it with the courier helper:

For Notification message you can use:

courier('notification')
    ->to('[e-mail]')
    ->line('This is a line')
    ->send()

For Mail message you can use:

courier('mail')
    ->to('[e-mail]')
    ->template('marketing')
    ->send()

And of course, you can use it in a template to render it:

<?= courier('mail')
        ->template('marketing')
        ->render()
        ->toHtml() ?>

Options

Here's an example of a full use of the options from the config.php file:

'beebmx.kirby-courier' => [
    'logo' => function() {
        return site()->file('logo.png');
    },
    'path' => 'courier',
    'from' => [
        'address' => '[e-mail]',
        'name' => 'Example',
    ],
    'message' => [
        'greeting' => 'Hello friend!',
        'rights' => 'Copyrights.',
        'salutation' => 'Thanks',
        'subject' => 'Message from courier',
        'notify' => 'Si tienes problemas para hacer clic en el botón, copia y pega la URL de abajo en tu navegador web.',
        'brand_name' => null,
    ],
],

License

Licensed under the MIT.

Credits

Kirby Courier is inspired by the Laravel Notifications and Laravel Mail.

• Fernando Gutierrez @beebmx
• Jonas Ceja @jonatanjonas logo
• All Contributors