DSCH Emails

Powered by:

Take a look at the MJML Guides for markup syntax.

Getting started:

NOTE: You may need to set nvm to use version >= 8, eg.

nvm ls

You'll see something like this:

->      v6.x.x
        v8.x.x
        v10.x.x
         system

nvm use v8.x.x (replace with your specific version, use tab to complete)

git clone [email protected]:distilledmedia/dsch-emails.git
cd dsch-emails
yarn install

Adding a new project

Run:

yarn create-project "newproject"

You will need to add your new project/brands to brands in config.js.

This will create the following folder structure:

├── newproject/                     * new project
 |   ├── common                     * directory to hold partial includes for templates
 |   ├── COMPILED_TEMPLATES         * output folder for this projects templates (.html)
 |   ├── templates                  * mjml template files

Commands available:

(See note above re nvm use)

$ yarn compile-emails

This will prompt you to pick a project that you would like to compile.

$ yarn compile-all-emails

As the name suggests this will compile all of your projects. This is handy if you are integrating with a CI.

$ yarn watch

This will allow you to work on an individual project and it will auto compile your templates on file change/save.

$ yarn create-project "newproject"

This will scaffold out a new project directory.

Project Structure

dsch-emails/
├─ projects/
|  └─ brand/
|     ├─ common                  * directory to hold partial includes for templates
|     ├─ COMPILED_TEMPLATES      * output folder for this projects templates (.html)
|     └─ templates               * mjml template files
│
├─ scripts/
|  ├─ compile.js                 *
|  ├─ create.js                  *
|  ├─ index.js                   *
│  ├─ inquirer.js                *
│  ├─ publish.js                 *
|  └─ watch.js                   *
│
├─ tools/                        * helper tools for running the project
|  | index.js                    * utilities
|  └─ logger.js                  * adds a touch of colour to console logs
|
├─ .babelrc                      * https://babeljs.io/docs/usage/babelrc/
├─ .editorconfig                 * http://editorconfig.org/
├─ .env                          * environment config
├─ .eslintrc                     * https://eslint.org/docs/user-guide/configuring
├─ .gitignore                    * https://git-scm.com/docs/gitignore
├─ config.js                     * global configuration
├─ package.json                  * https://docs.npmjs.com/files/package.json
└─ projects.config.js            * Configuration file for this project

Recommended Development Workflow

• Download and Install Visual Studio Code editor

• Install these VS Code extensions:

ESLint

Prettier (Code formatter)

MJML Syntax

MJML preview, lint, compile

• In VS Code, add the following settings by hitting the ⌘, keys together to open the Search settings input. Enter [json], then click Edit in settings.json below.

  "editor.formatOnSave": true,
  "editor.formatOnPaste": true,
  "prettier.singleQuote": true,
  "prettier.eslintIntegration": true,
  "editor.tabSize": 2,
  "editor.insertSpaces": true,
  "eslint.run": "onSave",
  "eslint.autoFixOnSave": true,
  "files.insertFinalNewline": true

Coding a template

• Code the required email using hard-coded data until happy with the design. Once the FreeMarker templating language is integrated, we can no longer leverage VS Code preview properly

• Do a quick check in Litmus to check that everything looks ok

• Add FreeMarker code to the template. Note that any missing variables will result in the email not being sent

• Prepare the template's code for Knocker (see below)

• Publish to Knocker. From here you can send emails by passing through template values

Preparing the code for uploading to Knocker

• Run

$ yarn compile-emails

• You'll be prompted to select the brand you want to compile

Each mjml file in the base of the selected brand folder will be compiled to html, minified and saved to /projects/[BRAND]/COMPILED_TEMPLATES/

For example: /projects/internal/templates/motor-loan.mjml => /projects/internal/COMPILED_TEMPLATES/internal-motor-loan-email.html

internal-motor-loan-email in this case will be the name associated with the template in Knocker

Publishing to Knocker sandbox

• Run

$ yarn publish-emails

This push all templates to Knocker. It will update them all and create any that are not there.

Create a payload json file

This file is used to send test emails via Postman. This is very valuable when coming back to a tempalte. This is required for each new template.

For each new template, create a similarly-named json file with the expected Freemarker variables in /projects/[BRAND]/payloads

Example of one for Daft Ad Reply email:

{
  "channel": "email",
  "template_name": "daft-ad-reply-email",
  "identifiers": ["[email protected]"],
  "template_values": {
    "subject": "New Enquiry",
    "title": "New Enquiry",
    "fromName": "Jane Doe",
    "fromEmail": "[email protected]",
    "fromPhone": "087 1234567",
    "message":
      "This is a message that you may see from a user enquiring about the property. It can be long sometimes.",
    "photoUrl": "https://placeimg.com/600/325/arch",
    "berRating": "D1",
    "mediaCount": "23",
    "hasVirtualTour": true,
    "hasVideo": true,
    "price": "€850,000",
    "address": "Mount Alverno, Sorrento Road, Dalkey, Co.Dublin",
    "numBedrooms": "2",
    "numBathrooms": "2",
    "cdnUrl": "https://dsch-emails-ss-staging.apps.dsch.ninja/email",
    "ctaUrl": "https://www.google.ie/"
  },
  "email_properties": {
    "subject": "New Enquiry",
    "from": "Daft.ie TEST <[email protected]>",
    "inline_css": false
  }
}

This is the reference payload structure that will be used by the backend in template_values when an email is sent.

Publishing to Staging/Production

Before continuing, ensure that:

• the template in the sandbox environment sends successfully (missing Freemarker variables may result in the email not being sent)
• the template has product & design approval
• the template has been QA approved
• the working branch has been PR approved against master
• any backend changes (if required) are ready for release

Once the above conditions are met:

• Squash and merge your branch to master
• Once you merge it will automatically kick off a pipeline and release to staging and then onto production
• At present, auto promotion to production happens after every merge so please ensure it was tested in sandbox first
• You can view the pipeline here (You must be on the Distilled VPN to view. Log in with Google)