README

Ugly problems often require ugly solutions. Solving an ugly problem in a pure manner is bloody hard.

-- Rasmus Lerdorf

PostBoy

Postboy is a simple tool to markup and prepare html mail. It utilizes nunjucks templates (with plugins) for building markup and juice for inlining CSS.

Note: This is unstable. The readme is unfinished. Go away! Well maybe put on track and go away :3. The behavior and API may and will change over time. Probably the entire thing will be rewritten after I make sure the tool has everything I need it to.

In future I hope to finish my own HTML parser and use it in postboy, until then the entire thing is a set of workarounds and ugly solutions.

Features

Features not yet implemented are bold-italic. Ones implemented partially or terribly unstable are italic

Nunjucks templating engine used.
Nunjucks extensions introduced for easier tables fiddeling.
Pre-set styles for embedding/inlined (e.g. images with display:inline-block et cetera)
ability to watch files for changes and compile them
you can setup an SMTP server to send test e-mails

Workflow (how postboy prepares letters for delivery)

you type postboy init and get a basic email template with some stuff already ses
compiles LESS files (embed.less and inline.less) if any
compiles nunjucks template (index.html file). Postboy adds its own plugin for tables. Also nunjucks-append, nunjucks-capture, nunjucks-date and nunjucks-markdown extensions used.
merges styles and classes. So duplicate class and style attributes are fine (for ease of nunjucks use)
wraps all anchor elements with <span> tag for Outlook styling
replaces html symbol entities with unicode representation (  becomes  )
inlines CSS styles from inline.css
removes CSS classes
embeds CSS styles from embed.css
replaces short-hand colors (#333 becomes #333333) (may be unstable)
replaces short-hand CSS properties
strips comments from HTML

Sending test e-mails via SMTP

If you have an access to some kind of a SMTP server - you can use postboy send to send an email to some destination. To do this - add send key in your pstboy.config.js:

send:{
  to: 'ilia@andrienko.org',
  server: 'mail.adm.tools',
  port: 25,
  login: 'noreply@server.com',
  password: 'someKindOfPasswordHere',
  subject: 'Test mail',
  from: 'Postboy <noreply@server.com>'
}

SMTP server, login and password are required, as well as to, which is is the address that the mails will be sent to. By default, subject will be current date and port will be 25, from will be "Postboy".

Sending test e-mails via gmail

Config must be same as with SMTP, but do not specify the "server" field and "login" field must be a gmail email (e.g., test.mailer.postboy@gmail.com or something like that).

You may also need to allow less secure apps in your gmail account, gmail itself will give you the instructions as you try to send first email if it fails.

Plans

fix empty tags (empty tags are now turning into self-closing)
add self-closing tags
move entities decoding to the end of workflow
sending via gmail or whatever nodemailer is capable of
Beautifies HTML
Validates XML for all your XSLT needs
Archives the templates
Produces different versions of templates
Watcher
Image sizes
integrate this: https://github.com/dudeonthehorse/normalize.email.css

Recommendations

There are several rules that apply to email mark-up. Of course, if you want it to look good in most popular mailing clients.

Use tables for mail. Really. CSS is kind of broken mostly in mailers.
It's HTML4. Because of outlook and stuff.
Specify image sizes. Every single image size. For god's sake.
Use inline styles. Gmail strips all styles but inline ones.
...

Okay, I think the recommendations would require me to write the entire article. Or a book maybe. Probably one day I will.

Initialization and file structure

To instsall postboy

npm install -g postboy

To initialize the project type

postboy init

This should create a couple folders with couple files in. All the sources will be contained within source folder.

!!!THE FOLDER STRUCTURE IS DIFFERENT NOW!!!

source/
-- css/
   -- inline.css - contains css styles that will be inlined in
                   elements (if the file exists).
   -- embed.css - styles that will be embedded in <style> tag
                  under <head> section if it exists or at the end
                  of the file if it does not.
-- common/
   -- layout.html - Main layout (html etc)
   -- macros.html - Macros file. If it exists it will be included
                    in all the files compiled by default.

To build the mail just type postboy. It will look for postboy.js file in a folder you typed it in.

Usage no npm install needed!