practio-email v1.1.0

practio-email

This service enables any other service to send an email. Practio-email listens to email.send commands, generates the email based on the template indicated in the command and then uses Amazon's Simple Email Service to send the email. The email.send command should have the following structure:

{
  to: 'someone@gmail.com', // required
  template: 'phoneBookingConfirmation', // required
  emailData: {
    ...any custom data needed by the template
  },
  locale: 'en-GB' // optional, will default to 'en-GB' if not set
}

It is also possible to includes attachments in the email by pointing to files stored on S3:

{
  to: 'someone@gmail.com',
  template: 'phoneBookingConfirmation',
  emailData: {
    ...any custom data needed by the template
  },
  locale: 'en-GB',
  attachments: [
    {
      bucket: 'bucketName',
      key: 'my-s3-file-key.pdf',
    },
    {
      bucket: 'bucketName',
      key: '6ff6a20d-0f3c-4309-8d9d-f6a219a06343.pdf',
      fileName: 'receipt.pdf', // you can provide a different name than the s3 key name for the file
    },
  ]
}

Development

Start the service with npm start.

Then navigate to http://localhost:10070/ to test out the templates you are developing.

Testing in different email clients

In order to check if the email looks fine in different email clients you can use litmus.com. In 1Password search for litmus to find the user for our account.

Sending emails locally

Create a new file called auth.json and add the following information:

{
  "aws": {
    "sesAccessKeyId": "COPY_FROM_HEROKU_STAGING",
    "sesSecretKey": "COPY_FROM_HEROKU_STAGING"
  }
}

Head to Heroku staging practio-email app and copy the following Config Vars:

• AWS_SES_ACCESS_KEY_ID
• AWS_SES_SECRET_KEY

Note: this will only work with @practio.com mail addresses.

Templates

Templates are defined in the /server/emails/templates folder (they are server-side rendered). All HTML used inside a template must be done with MJML, to ensure that our emails work across many different email clients and that they are responsive.

All template names must be exposed in the @practio/email-templates module found in the packages folders here. So when you add a new e-mail template, then remember to publish a new version of the module by running npm run publish in the root of this repository.

Email assets

All assets used in emails (typically pictures) can be added to the /assets/ folder where they can be accessed for local development.

For staging and production these assets must also be added to the AWS S3 bucket containing our assets called email-assets.practio.com found here.

All these assets will be served via Cloudfront which you can see by looking at the assetsUrl property in the staging and production config files.