Kirby Mailjet (BETA)

Kirby Mailjet makes sending emails with Mailjet simple.

It's php helper class allows you to send transactional emails, as well as test and publish newletters. In combination with the Kirby Opener Plugin you can do all that from within the Panel.

An example template and controller are provided to help you getting started with styling your own emails using Kirby Builder, the responsive email markup language mjml and the logic-less templating language Mustache PHP. But if you have your own toolchain to create responsive HTML code for emails you can continue using it.

NOTE: This is not a free plugin. In order to use it on a production server, you need to buy a license. For details on Kirby Mailjet's license model, scroll down to the License section of this document.

Key Features

swap your email service from mail to kirby-mailjet and start sending emails using Mailjet
sent emails can be assigned to new or existing Campaigns
add attachements to emails
add and remove Contacts from Contactslists
test and publish Newsletters
publish Newsletters on a Schedule
choose Mailjet Sender Adress
Panel Fields to access Contactslists and Segments
Panel Buttons to send tests and publish (Kirby Opener required)
example how to create responsive HTML emails

Requirements

Kirby 2.4+
Mailjet Account, free plans available

Included Dependencies

Installation

Kirby CLI

kirby plugin:install bnomei/kirby-mailjet

Git Submodule

$ git submodule add https://github.com/bnomei/kirby-mailjet.git site/plugins/kirby-mailjet

Copy and Paste

Download the contents of this repository as ZIP-file.
Rename the extracted folder to kirby-mailjet and copy it into the site/plugins/ directory in your Kirby project.

Setup Mailjet Account

Create a Mailjet account if you do not have one already.

add a sender domain AND at least one sender email-adress here
authentificate you domain here
create a Test contactslist and add one of your own email-adresses to it.
set your API Public and Secret Keys and default sender-email-adress in your Kirby /site/config/config.php file.

c::set('plugin.mailjet.apikey',    'YOUR_KEY_HERE');
c::set('plugin.mailjet.apisecret', 'YOUR_SECRET_HERE');
c::set('plugin.mailjet.from',      'YOUR_SENDER_EMAIL_ADRESS_HERE');

Plugin Usage

Updating Contactslists

You can call the helper class to add or remove contacts from a contactslist. If you defined custom contact properties you can forward these to the api as well.

Tip: If you provide a string and the contactslist does not exist, it will be created.

KirbyMailjet::updateContactslist(
  'contactslistnameOrID',
  KirbyMailjet::LIST_ADDFORCE, // or LIST_ADDNOFORCE, LIST_UNSUB, LIST_REMOVE
  [
    'email' => 'test@example.com',
    //'firstname' => 'max', // custom contact property
  ]
);

Tip: Check out the example on how to build your own newsletter double optin logic.

Sending Transactional Emails

Transactional means sending an email to one person, not to a Constactslist with many people. To do so you can call the helper class directly or use the email service this plugin provides.

// if you did set config...
// c::set('plugin.mailjet.from', 'my@email.com');
// ... you can get default sender adress
$senderEmail = KirbyMailjet::senderAdress();

// or set now
$senderEmail = KirbyMailjet::senderAdress('my@email.com');

$options = array();
// you could add this email to a Campaign to filter by
$options['Mj-campaign'] = 'Any Campaign';

// or add some attachments, assuming a Kirby Media object
// https://dev.mailjet.com/guides/#sending-with-attached-files
$attachedFile = [ 
  'Content-type' => $file->mime(),
  'Filename' => $file->filename(),
  'content' => base64_encode($file->content()),
];
$options['Attachments'] = array($attachedFile); // must be array even if only one file

$params = [
  'to'      => 'email@example.com',
  'from'    => $senderEmail, // this must be a valid sender email-adress
  'subject' => 'Sending emails with Kirby Mailjet is easy',
  'body'    => 'Hey! This was really easy!', // or responsive HTML code
  'service' => KirbyMailjet::EMAIL_SERVICE, // this is important!
  'options' => $options,
];

// https://getkirby.com/docs/cheatsheet/helpers/email
$email = email($params);
if($email->send()) {
  echo 'The email has been sent';
} else {
  echo $email->error();
}

// or just call the helper class instead
if(KirbyMailjet::sendMail($params)){
  echo 'The email has been sent';
} else {
  echo $email->error();
}

Testing and Publishing Newsletters

$senderEmail = KirbyMailjet::senderAdress();
// or
$senderEmail = KirbyMailjet::senderAdress('my@email.com');
// or
if ($page->mjsender()->isNotEmpty()) {
    $senderEmail = $page->mjsender()->value();
}

// the subject is most important since that will be used 
// to identify your Newsletter in combination with 
// choosen Contactslist and Segment.
// if you change any of these you can publish it again
// since its treated like a new one by this plugin.
// so be careful with these three fellows.
$subject = trim($page->title());

// set an unique title for mailjets dashboard.
// this is never seen by newsletter reciepients.
$title = date('Y-m-d H:i:s'); // just an example

// mailjet will not accept urls bigger than 100 chars
// for this property, even if this is used in dashboard only.
// urls within the html content can be longer than 100 chars.
$url = $page->url();
if(strlen($url) > 100) {
  $url = $page->tinyurl();
}

// these fields are required, you have to provide each of them
$campaign_body = [
  'Locale' => "en", // 'de_DE', ...
  'SenderEmail' => $senderEmail,
  'Sender' => KirbyMailjet::senderName(), // will get name from mailjet for you
  'Subject' => $subject, // UNIQUE for this Newsletter
  'Title' => $title,
  'Url' => trim($url),
];

// if you want to filter a contactslist 
// use a segmentation (only mailjet premium subscription)
if($segid = KirbyMailjet::getSegment($segmentationNameOrID)) {
  $campaign_body['SegmentationID'] = $segid;
}

$campaign_content = [
  'Html-part' => $html, // here goes your content
  'Text-part' => "Some plain text fallback with a link to the online version of the newsletter. ".trim($page->url()),
];

KirbyMailjet::sendNewsletter(
  'contactlistsnameOrID',
  $campaign_body,
  $campaign_content,
  'my@email.com', // email-adress to send test to or string 'Publish'
  $schedule, // `null`/`'now'`, a timestamp or an ISO 8601 formatted date (`date('c')`) at UTC
);

// you can enable logging in config file like this
// c::set('plugin.mailjet.logfile', YOUR_PATH_TO_FILE);
// or check for errors now
if(KirbyMailjet::hasErrors()) {
  a::show(KirbyMailjet::errors());
}

schedule timezone convert example

$schedule = null;
if ($page->mjscheduledate()->isNotEmpty() && $page->mjscheduletime()->isNotEmpty()) {
  $schedule = $page->mjscheduledate()->value() . 'T'. $page->mjscheduletime() . ':00';
  $date = new \DateTime($schedule, new \DateTimeZone('Europe/Berlin'));
  $date->setTimezone(new \DateTimeZone('UTC'));
  $schedule = $date->format(\DateTimeInterface::ISO8601);
}

Responsive HTML Emails Example

You can find the example readme here.

Other Setting

You can set these in your site/config/config.php.

plugin.mailjet.license

default: ''
add your license here and the widget reminding you to buy one will disappear from the Panel.

plugin.mailjet.apikey (required)

default: ''
add your mailjet api key.

plugin.mailjet.apisecret (required)

default: ''
add your mailjet api secret.

plugin.mailjet.from (required)

default: ''
add your default mailjet sender adress here.

plugin.mailjet.hash

default: unique hash for your webserver
this value is used to create the hash and you should set your own value to improve security but it is not required. it is used by the routes for the Contactslists and Segments Panel Fields.

plugin.mailjet.examples

default: false
if disabled the plugin does not install any blueprints, templates, controllers, hooks and routes that are used by its examples. disable this setting in production enviroment.

plugin.mailjet.logfile

default: false
set this value to the path of a file where you want the log to be written to.

c::set('plugin.mailjet.logfile', kirby()->roots()->site().DS.'logs'.DS.'mailjet-'.date('Ym').'.log');

plugin.mailjet.json.cache

default: 300
time in seconds to cache the json files for contactslists and segments

plugin.mailjet.json-contactslists.exclude

default: []
array of numeric ids to exclude from the contactslists.json

plugin.mailjet.json-segments.exclude

default: []
array of numeric ids to exclude from the segments.json

plugin.mailjet.mjml-command

default: mjml
you could set the full path to mjml executable here if needed

Localisation

English and german languages are provided. You could PR another if you create one.

Disclaimer

This plugin is provided "as is" with no guarantee. Use it at your own risk and always test it yourself before using it in a production environment. If you find any issues, please create a new issue.

License

Kirby Mailjet can be evaluated as long as you want on how many private servers you want. To deploy Kirby Mailjet on any public server, you need to buy a license. You need one unique license per public server (just like Kirby does). See license.md for terms and conditions.

If you purchase a license during ALPHA you can get 50% off using this coupon code KIRBY-MAILJET-ALPHA.

However, even with a valid license code, it is discouraged to use it in any project, that promotes racism, sexism, homophobia, animal abuse or any other form of hate-speech.

Technical Support

Technical support is provided on GitHub only. No representations or guarantees are made regarding the response time in which support questions are answered. But you can also join the discussions in the Kirby Forum.

Credits

Kirby Mailjet is developed and maintained by Bruno Meilick, a game designer & web developer from Germany. I want to thank Fabian Michael for inspiring me a great deal and Julian Kraan for telling me about Kirby in the first place.

bnomei / kirby-mailjet