Skip to content

Latest commit

 

History

History
97 lines (54 loc) · 4.96 KB

README.md

File metadata and controls

97 lines (54 loc) · 4.96 KB
Raw

Courier plugin for Craft CMS

Manage the automated delivery of custom emails, triggered by certain pre-determined events and conditions.

Screenshot

Requirements

This plugin is tested in and works with Craft 2.6.x, and requires PHP 5.4 or above.

Installation

To install Courier, follow these steps:

  1. Download & unzip the file and place the courier directory into your craft/plugins directory.
  2. Alternatively, you can git clone https://github.com/therefinerynz/courier.git directly into your craft/plugins folder. You can then update it with git pull.
  3. Install Courier in the Craft Control Panel under Settings > Plugins.

Overview

Courier is a Craft CMS plugin that allows you to create and manage email “Blueprints”. A Blueprint determines which event and conditions should trigger an email, general settings for the email, and which templates should be used for the email body.

Features

  • Listen for any event (including core Craft CMS events or events triggered by a plugin), and conditionally send an email
  • Create and manage Blueprints to configure email settings, and the conditions that should be met before an email is sent
  • Craft global sets and event parameters are available for use with Twig in most of a Blueprint's settings fields
  • Add multiple recipients to an email with the use of a Blueprint's CC and BCC fields.
  • Complete control over email template structure, and where email template files should be sourced.
  • Ability to use both HTML and Text email templates with each email.
  • All email templates have access to the relevant Blueprint model, Craft global sets and any parameters made available on the event itself
  • Track when emails were sent and view any errors that were raised while rendering or trying to send an email in the “Deliveries” section.

Settings

From the plugin settings page you can define which events you might watch for when setting up your Blueprints, and how many delivery records should be retained.

Screenshot

Craft CMS Email Settings

Before setting up Blueprints in Courier, ensure that your Craft CMS installation has email configured correctly.

You can set up your email gateway in the Craft CMS control panel by going to Settings ⟶ Email.

We recommend using a transactional email service such as Mailgun. Further information on troubleshooting email errors in Craft CMS can be found here.

Usage

A common use case for Courier would be setting up a Blueprint to listen for the save of new Contact message entries submitted by anonymous visitors on the front-end of your site through a contact form. This is made possible by using Courier in conjunction with Pixel & Tonic's Guest Entries plugin.

If you were to set up two Blueprints for this use case, you could send two different emails. One to alert the admin of a new message that was submitted which could include the relevant entry information (message, guest's contact information, etc.), and one to thank the guest for their message.

Creating a Blueprint

After you've installed the plugin, go to Courier in the control panel sidebar and click "New Blueprint"

A wiki will soon be set up with additional detail on Blueprint settings. In the interim, the following should provide some guidance:

HTML and Text Email Paths

The Twig templates used to generate the HTML and Plain Text body of your email. Paths should be relative to your templates directory.

To Email

The 'TO' address for this email. Due to limitations in the way Craft 2 sends emails, you cannot have multiple recipients in the To Email field.

CC and BCC Email(s)

To add multiple email addresses to a Blueprint's CC or BCC fields, simply separate each email address with a comma or semicolon.

Event Triggers

Which event(s) you want to trigger a Blueprint's email. Additional custom events can be added in the plugin settings page.

Event Trigger Conditions

Twig conditions to run after a watched event is fired.

  • Have this field's code evaluate to a single true if you want the event to trigger the Blueprint's email.
  • Have it evaluate to a single false if the blueprint should ignore the event.

You might have the Guest Entries plugin set up to accept front end submissions from guests, and save entries to a section with an ID of 11. The screenshot below provides and example of how a Blueprint might be set up to send an email when a new entry is created in that section:

Screenshot

TODO

  • Set up WIKI

Feedback

If you come across any problems with Courier, or if you have any suggestions or questions, please open an issue.

Credits

Brought to you by The Refinery.