responsive-html-email-signature: email templates built from a config and a stylesheet

The problem is the clients, not the templates

The framing of the project is unusually blunt about what it is for. The readme opens with the idea of punching email clients in the stomach, and the summary is that when you need responsive email signatures that work on mobile and your colleagues need them too, but you do not want to deal with tables and inline styles. The motivation section puts the limit plainly: writing HTML emails and email signatures sucks, we cannot fix all email clients, but we can surely make our lives easier with some automation. That is the right expectation to hold, because a generator can produce a well-formed email but it cannot make a broken client behave. The primary language of the repository is HTML, the licence is MIT, and the last push was on 2026-08-05 with the most recent tagged release being v6.2.0 from 2022, so the tool itself has been stable for a long time while the surrounding npm ecosystem has moved on.

Three commands and a watcher

Getting started is a clone, an install and a start, and the start command is the important one because it does not exit:

$ npm install
$ npm start # By default, templates will be created in `./dist` and HTML & CSS files in './templates' will be watched for changes.

The comment in that block tells you both halves of the behaviour. The templates are created in the dist directory, and the HTML and CSS files in the templates directory are watched for changes, so the build re-runs as you edit. That is what makes the workflow pleasant: you change a colour in a stylesheet and refresh the browser to see the result. The scripts in the package manifest separate the one-shot build from the watching one, with once running the gulp run-pipeline task and start running gulp itself, plus a watch variant of the test script. There is a node version caveat, tested with node versions 12 to 17, with the note that earlier and later versions might also work, which is the sort of statement you should check against your own machine rather than trust.

What the pipeline actually does to your files

The readme lists the pipeline's jobs as a checklist, and each item corresponds to a step you would otherwise do by hand. It generates email templates from your config, allows generating multiple templates at once for your colleagues, transforms linked CSS into inline styles, embeds local img[src] references into the template as base64, minifies the template, adds some basic media queries for mail clients that support them, can build templates from multiple sources, watches HTML and CSS files for changes and re-builds, supports LESS, SASS and PostCSS, runs autoprefixer so you do not have to worry about your vendor prefixes, lints and checks for used template config parameters, and can build and deploy templates to S3 automatically. The dependency list in the package manifest matches that list closely, with gulp-inline-css for the inlining, gulp-inline-images-no-http for the base64 embedding, gulp-minify-html, gulp-autoprefixer, gulp-less, gulp-jsonlint and gulp-david. The interesting one is the images step, since a mail client that blocks remote images by default will show nothing for a signature unless the image travels inside the message.

Config values, and an array for the same template twice

A template is configured through a conf.json file, and the dark template in the documentation shows the shape of it, with an id used for the filename, a signature, a name, contact fields, a slogan, a logo URL and a logo alt text, and a website:

{
  "id": "<will-be-used-for-filename>",
  "signature": "<signature-of-choice>",
  "name": "<your-name>",
  "contactMain": "<phone-or-email-or-html>",
  "contactMail": "<email>",
  "slogan": "<a-basic-slogan>",
  "logoUrl": "</assets/dark.png?>",
  "logoAlt": "<text-in-case-logo-is-blocked>",
  "website": "<http://dark.dk>"
}

The logoAlt field is there because a blocked image needs a text alternative, and the documentation points out that config variables also accept HTML, which is useful for including links. To generate several emails from the same configuration, you use an array instead of an object, in the form [{ ...conf1 }, { ...conf2 }], which is the feature that lets a whole team get the same signature without a new configuration file each. A configuration can also be generated from a shell script, since the manifest has a generate:conf script that takes a theme, a phone country code, a phone number and an email address as arguments.

Preprocess directives, and the variables they expose

Config variables are made available in all the HTML files, and the syntax for using one is an echo comment:

<p><!-- @echo yourCustomVariable --></p>

The value comes from the configuration file, where the same key is defined with the value Custom! in the example. The template syntax is not a language invented for this project: inside the HTML files, any preprocess directive is supported, such as @if, @extend and @exec, and the documentation links to a general preprocessing implementation. That choice is what makes the templates ordinary HTML files you can open in an editor, and it is also what means the templating is limited to what a text preprocessor can do, which is a reasonable trade for email where the alternative is a template engine that emits its own syntax. Templates can also contain multiple HTML files, each treated as a separate email, except for the partials convention described next.

Partials, and a directory per template

Files named with the .inc.html suffix become partials. They are not treated as templates, so they are ignored by the build, but they can be included in any HTML template using an include comment:

<section>
<!-- @include footer.inc.html -->
</section

Partials are for the bits of HTML that repeat, such as headers and footers. The structure of a template directory is not fixed by the project, but the documentation recommends creating a directory per template group, and it shows the dark template laid out with an assets directory holding the base64-embedded image, a conf.json, a dark.css stylesheet, a footer.inc.html partial for contact information and logo, a head.inc.html partial for the responsive CSS, a full signature.html that loads head and footer, and a signature-reply.html which is the simplified version loading only the head. That last pair is a good example of the partials paying for themselves, since a reply signature and a full signature differ by one include.

Deploying to S3, and the size limit you cannot ignore

Building templates can be automated in S3, and the manifest has a deploy script that runs the tests, copies the dist directory into the demo directory and then pushes it to the gh-pages branch with a git subtree split, and there is a separate generate:conf script for producing a configuration from shell variables. The caveat that appears in the readme is the one to respect. Some mail clients have hard limits on email size, so the advice is not to include large images if possible, and to use a URL instead and host the image somewhere else. That is a direct trade against the base64 embedding that the rest of the pipeline does, and it is the main thing to think about when you set the project up. The project also runs a linting step that checks for used template config parameters, which catches the common mistake of a config key that is spelled differently in the file and in the HTML.

Editorial conclusion

This project suits a team that has to send the same email or signature to colleagues on several clients and does not want to maintain tables and inline styles by hand, and it suits anyone who needs one source of truth for a signature. It does not suit a workflow where the email body comes from a marketing tool, and it does not fix the parts of email that cannot be fixed, since the goal stated in the readme is explicitly to make life easier rather than to repair every client. Before you build, check the size budget, because some mail clients have hard limits on email size and the documentation advises using a hosted URL for large images instead of embedding them.

Frequently asked questions

Official sources

1. danmindru/responsive-html-email-signature on GitHub
2. License: MIT
3. Project website
4. README
5. Releases