Crafting Impressive Responsive HTML Email Signatures

npm license test action status

Let’s Conquer Email Clients with Impressive Signatures 👊

When you require simple yet responsive email signatures that function flawlessly on mobile devices… and your coworkers want them too… but without the hassle of dealing with tables and inline styles.

Read the documentation in different languages here.


Here are some examples:

Getting Started

  1. Clone the repository: git clone
  2. Run npm install
  3. Run npm start to generate templates from the configuration. The template will continue to update whenever you make changes until you exit.

🪄 Automate Template Building with S3

Check out this guide to automate template building in S3.

Customizing Templates

  • Edit files in the /templates directory.
  • Open files from ./dist in your favorite browser to preview them.

Once you’re done, learn how to add them to your email client of choice if you’re not sure.


Writing HTML emails and email signatures can be a tedious task. Let’s simplify it. While we can’t fix all email clients, we can certainly make our lives easier with automation.

What Does This Code Do?

This code:

  • Generates email templates based on your configuration.
  • Allows you to generate multiple templates at once (for your colleagues too!).
  • Converts linked CSS into inline styles.
  • Embeds local images into the template (base64-encoded).
  • Minifies the template.
  • Includes basic media queries for mail clients that support them.
  • Supports LESS, SASS, and PostCSS.
  • Automatically builds templates from multiple sources.
  • Watches HTML/CSS files for changes and rebuilds.
  • Provides support for autoprefixer, minimizing concerns about -moz-s or -webkit-s.
  • Offers linting to check for used template config parameters and more!
  • Facilitates automatic build and deployment of templates to S3.

NB: Some mail clients may impose size limits on emails, so avoid including large images whenever possible. In such cases, use a URL and host the image elsewhere.



⚠️ Please note that this project has been tested with Node versions 12-17. Earlier and later versions might also work.

See also  How to Apply for a Kenya E-Visa


To create a basic email from existing templates, simply edit the conf.json file in each template.

For example, the dark template accepts the following configuration:

Generating Multiple Emails from the Same Configuration (for your colleagues too!)

To generate multiple templates, use an array instead of an object in conf.json. Here’s an example:

Using Config Values in HTML

Config variables are accessible in all HTML files. Add any variable to the configuration file and use it in HTML like this:

Where the configuration contains:

NB: Config variables can also accept HTML, which is useful for including links.

Adding CSS and Preprocessing

You can include any number of CSS, SASS, or LESS files in a template directory, and they will be automatically processed and inlined into the output files in ./dist.

Managing Multiple Emails in the Same Template

Templates can contain multiple HTML files to build emails. For example, the dark template has signature.html and signature-reply.html, which is a simpler version. Each HTML file is treated as an email template. However, files with the extension *.inc.html are ignored.

Using Partials (*.inc.html)

By naming files with the *.inc.html extension, they become partials. Partials are not treated as templates, but they can be included in any HTML template using the @include HTML comment.

Partials are useful when you have repeated bits of HTML, such as headers or footers.

Advanced Templating

Inside HTML files, you can use any preprocess directive, such as @if, @extend, @exec, and more.

Template Structure (Examples)

There are no strict rules regarding how to structure templates, but it’s a good idea to create directories for template groups. Here are examples of the structures for the light and dark email templates:

You are encouraged to modify the default structure to suit your specific needs.

Automate Signature Creation

Use the Github Actions Workflow to automatically generate and store your signature in a cloud storage (e.g., S3 Bucket). Refer to the sample Github action below:

  1. Create the bucket to store the signature using AWS CLI:

    aws s3 mb s3://<BUCKET_NAME>

    Replace <BUCKET_NAME> with the unique name of your S3 bucket.

  2. Deploy the role with permission to upload signatures into your account’s S3 Bucket:

    aws cloudformation deploy -template-file cicd/github_generate_email_role.yaml -stack-name githubOidcGenerateEmail -capabilities CAPABILITY_NAMED_IAM
  3. Populate the secret values AWS_REGION, EMAIL_ADDRESS, MOBILE_PHONE_COUNTRY_CODE, BUCKET_NAME, MOBILE_PHONE_NUMBER, and GH_GENERATE_EMAIL_ROLE in the repository’s settings tab.

  4. Trigger the generate-email-signature workflow manually.

  5. Congratulations! 🥳 Your signature has been uploaded. You can now download it from your S3 Bucket.

See also  Boost Your Sales with Sales Funnel Templates

Overview of the Build Process

The diagram below illustrates the transformation of your email templates. Each folder in the templates directory is considered a template group. For each configuration object you have in the template group’s conf.js, a template file will be generated.

CSS Support

Remember, HTML emails require some extra care. Check out a comprehensive guide to ensure everything works as expected. Although gulp-inline-css is utilized to convert CSS into inline styles, it may not handle all cases.

Using gulp-inline-css offers some benefits, such as converting many CSS properties into attributes. For instance, the background-color property will be added as the bgcolor attribute to table elements. For more details, refer to the inline-css mappings.

Usage with Different Email Clients


There are several Thunderbird plugins that can automatically insert signatures when composing emails. We recommend SmartTemplate4 as one of the options. It allows you to use different templates for new emails, replies, and forwarded emails.


To add your signature in Gmail:

  1. Go to your mailbox settings.
  2. Paste the generated signature.

NB: Gmail does not support inlined (base64) images. Use absolute URLs instead.

Office 365 /

It’s a bit tricky to set up, but it is possible. Please refer to this issue for more details.

Apple Mail / OS X (oh boy)

Solution 1

  1. Open and go to Mail -> Preferences -> Signatures.
  2. Create a new signature and enter some placeholder text (the contents don’t matter, but you’ll need to identify it later).
  3. Close
  4. Open Terminal and open the signature files using TextEdit (the process may differ for iCloud Drive, so please check the relevant article).
  5. Keep the file with the placeholder text open and close the others.
  6. Replace the <body>...</body> and its contents with the template of your choice. Do not remove the meta information at the top.
  7. Open and compose a new email. Select the signature from the list to test it.

NB: Images may not appear in the signature preview but will work fine when you compose a message.

Solution 2

Alternatively, you can open the HTML files in /dist in a browser, press CMD + A, CMD + C, and then paste it into the signature box. This method will not copy the <html> and <style> sections that include media queries. Refer to the guide if you want to include them.

See also  Introducing the <ins> HTML Tag


If Solution 1 doesn’t work, you can repeat the steps and lock the signature files before reopening

To lock the files:

chflags uchg /path/to/file

To unlock the files:

chflags nouchg /path/to/file

If you’re using iCloud Drive or experiencing any issues, please consult this article.

Outlook 2010 Client for Windows 7

Solution 1

  1. Open Outlook 2010 and go to File -> Option -> Mail -> Signature.
  2. Create a new signature (with a placeholder for convenience).
  3. Open the signature folder using CMD.

To access the AppData folder, I recommend opening it via CMD.

  1. In the folder, find the file with your placeholder text, right-click it, and select “Edit.”
  2. Replace the contents with your HTML and save the file.
  3. Open Outlook again and check your signature.

Solution 2

Unfortunately, Outlook 2010 client does not support importing HTML files for email templates. However, you can manually add your own signatures by copying and pasting, as mentioned in Solution 2 above.

NB: Base64 images will not be shown in the Outlook 2010 client. For images, use external URLs.

Other Commands

npm run test

Runs tests once.

npm run once

Creates templates and exits without watching files.

Check out the ProgramMatek suite for more great tools.