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:
- Clone the repository:
git clone https://github.com/danmindru/responsive-html-email-signature.git
npm startto 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.
- Edit files in the
- Open files from
./distin 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?
- 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.
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
Managing Multiple Emails in the Same Template
Templates can contain multiple HTML files to build emails. For example, the dark template has
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 (
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.
Inside HTML files, you can use any preprocess directive, such as
@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:
Create the bucket to store the signature using AWS CLI:
aws s3 mb s3://<BUCKET_NAME>
<BUCKET_NAME>with the unique name of your S3 bucket.
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
Populate the secret values
GH_GENERATE_EMAIL_ROLEin the repository’s settings tab.
Congratulations! 🥳 Your signature has been uploaded. You can now download it from your S3 Bucket.
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.
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.
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:
- Go to your mailbox settings.
- Paste the generated signature.
NB: Gmail does not support inlined (base64) images. Use absolute URLs instead.
Office 365 / outlook.live.com
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)
- Open Mail.app and go to Mail -> Preferences -> Signatures.
- Create a new signature and enter some placeholder text (the contents don’t matter, but you’ll need to identify it later).
- Close Mail.app.
- Open Terminal and open the signature files using TextEdit (the process may differ for iCloud Drive, so please check the relevant article).
- Keep the file with the placeholder text open and close the others.
- Replace the
<body>...</body>and its contents with the template of your choice. Do not remove the meta information at the top.
- Open Mail.app 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.
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
<style> sections that include media queries. Refer to the guide if you want to include them.
If Solution 1 doesn’t work, you can repeat the steps and lock the signature files before reopening Mail.app.
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
- Open Outlook 2010 and go to File -> Option -> Mail -> Signature.
- Create a new signature (with a placeholder for convenience).
- Open the signature folder using CMD.
To access the AppData folder, I recommend opening it via CMD.
- In the folder, find the file with your placeholder text, right-click it, and select “Edit.”
- Replace the contents with your HTML and save the file.
- Open Outlook again and check your signature.
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.
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.