eladnava/mailgen

A Node.js package that generates clean, responsive HTML e-mails for sending transactional mail.

mailgen's Issues

cache theme html file

Currently if you generate 5000 emails it will synchronously load the theme file 5000 times: https://github.com/eladnava/mailgen/blob/master/index.js#L51

It would be better to keep the theme html file content into memory so that the generate function won't try to read it each time from disk. That would be a massive improvement.

Normalize line breaks in plaintext versions of generated e-mails

Currently, when calling mailgen.generatePlaintext(email), the string returned looks something like this:

Hi John,
Welcome to Mailgen! We’re very excited to have you on board.



To get started with Mailgen, please click here:
https://mailgen.js/confirm?s=d9729feb74992cc3482b350163a1a010
To read our frequently asked questions, please click here:
https://mailgen.js/faq




Need help, or have questions? Just reply to this email, we\'d love to help.

Yours truly,
Mailgen

The line-breaks are either excessive or missing. What I think we should do instead is ignore \n line breaks in the index.txt theme files and instead have each theme indicate a line break by a <br /> tag, even though the plaintext version isn't supposed to have any HTML. Mailgen will replace all <br /> tags with a \n line break.

This would be a breaking change, but I'm thinking of running this replace logic only if the current theme's plaintext file contains at least one <br />, to avoid this being a breaking change.

Attachment

Any plan for to support attachment?

Scheduling with mailgen

Are you thinking of adding scheduling to this module any time soon or do you want me to create a pull request?. It will come in handy

Having buttons inside of tables

Hi mailgen team, I looked through the code and didn't see anything that allows you to add buttons to tables, in our use case we need to add links to individual items in the table.

Is something like this currently doable ? and I just haven't figured it out?

Add text links for button actions

As we all know, we have a mail client friend, called Outlook, that doesn't like to follow standards or always has weird behaviours. This in turn meant that buttons and their actions may sometimes not be shown (#16 can be an example).

I would propose not only trying to keep buttons being shown on outlook clients, but also provide an escape route. Normally emails come with "Can't see/click the button? Try the full link instead: example.com".

Maybe this can be a good middle ground for this problem?

Improve flexibility of email contents

The email contents values suit the three examples well, but are a little limiting if you're trying to create more generic emails.

The first thing I noticed on this was name being output after the language greeting (e.g. Hi). Perhaps this could just be title and allow the entire contents of this title to be managed in one value?

The second thing I noticed was the lack of flexibility with paragraphs. Mail contents need to fit within an action or table which may not suit simple emails with a few paragraphs. Supporting an array of paragraphs would be great, and perhaps a definition list for blocks like this:

JSON Schema for mailgen format available?

I write mail templates in JSON for mailgen, but would like to provide a JSON schema to do so.
Anyone aware of the existence of a JSON schema for mailgen?

Threading Emails

I would like to send emails that are part of an existing thread. I'm using mailgen to generate them, and mailgun to send the emails. Is it possible to use X-Entity-Ref-ID to let these emails know that they are all part of a single thread?

Thanks!

Ability to add Logo to email header and footer

It would be great if we had an option to add an image along with text content as part of name property, so that we can have logo as part of header and footer

Currently only text content are allowed as part of header and footer

Expected Config Example:

const mailGenerator = new Mailgen( {
  theme: "default",
  product: {
      name: "NAME",
      image: "LOGO.png"
  }
} );

Thanks!

feature request: tabular data

Would be nice to also have some way to produce tabular data. Labels on the top or left. Maybe pass in an array of data and it builds the table for you.

Action button -- alignment option in default theme?

Hi there and thank you for your work on mailgen -- it's been very easy to use.

The 'default' theme is nearly perfect for a project I'm working on, but I would like the button in the action section to be aligned left, just like the text.

It seems that besides 'color', 'text', and 'link', there isn't an option such as 'alignment' that I can give to 'button' in the email body object:

var email = {
    body: {
        name: '...',
        intro: '...',
        action: {
            instructions: '...',
            button: {
                color: '#22BC66',
                text: 'Button text',
                link: 'https://...',
                alignment: 'left' // currently not supported
            }
        },
        outro: '...'
    }
};

Is my best option here to make a custom theme nearly identical to the default template, but just change the button formatting according to what I need? Definitely not a major issue to do this, but I just wanted to check that currently this would be the recommended approach and that there is no feature in the works for a button alignment option. Thanks!

make theme option more usable

https://github.com/eladnava/mailgen/blob/master/index.js#L16-L22

Currently there's no way to add a custom theme without interfering with the module's /themes folder. I believe the theme option should be a path to a specific theme html file, not a name. That would make it more user friendly.

Button Styling Looks Off In MS Outlook Web

This image shows the button I get when viewing my email (with the default theme) in outlook web. It looks fine on MS Outlook's desktop app, it just look funny in their web app. I believe it has something to do with the line height, but I might be mistaken. Any idea how to fix this without using a custom theme?

Max Width Property on Email Logo

There seems to be no max-width property on the email logo with the Salted Theme.
Is there any way this could be limited? On Outlook, some logos take up almost the entire screen if the image is too big.

This logo property is set in the product object when setting a theme.

Thanks!

i18n support

it would be really cool to add i18n support, i'm from Perú where we need to send emails in spanish, right now we are customizing the template to achieve that but it would be really great to have i18n support backed in the library itself.

how would you like to implement this? i can work on it if you like but i want to discuss the details first.

i was thinking that creating a i18n folder inside each theme would be a nice approach, inside the i18n folder would be a json file for each language, inside the template files (.html, .txt) we would need to use that content depending of the language chosen by the consumer.

we would need to create a new option in the MailGen constructor, something like lang, of course if this option is not specified it will default to en.

what do you think?

product logo from local disk

I wanted to use logo from my local system -
var mailGenerator = new Mailgen({
theme: 'cerberus',
product: {
// Appears in header & footer of e-mails
name: 'abc,
link: 'https://www.abc.co',
logo: 'images/logo.png' HOW TO ADD RELATIVE PATH HERE ?
// Optional product logo
// logo: 'https://mailgen.js/img/logo.png'
}
});

Copyable link was removed

1944ccb removed the plain text version of action links that could be copied and pasted into browsers.

As #16 demonstrates that the button is invisible on Outlook, it really does make sense to have this as a fallback.

I was wondering why it was removed?

Type issue for Button

Documentation states that color is optional for Button but type file defines it to be mandatory.

See

color: '#22BC66', // Optional action button color

And type definition

interface Button { color: string; text: string; link: string; }

Email Layout Breaks in iOS Email App

Bug Description

It seems that the layout breaks in iOS email app, but not in GMail and Outlook app.

How to Reproduce

Sent an email using Mailgen template, and open it in the device

Screenshot

Throws an error when using table in side body

I tried with the below sample code which provided in README.md file with Type Script

var email = {
    body: {
        name: 'John Appleseed',
        intro: 'Your order has been processed successfully.',
        table: {
            data: [
                {
                    item: 'Node.js',
                    description: 'Event-driven I/O server-side JavaScript environment based on V8.',
                    price: '$10.99'
                },
                {
                    item: 'Mailgen',
                    description: 'Programmatically create beautiful e-mails using plain old JavaScript.',
                    price: '$1.99'
                }
            ],
            columns: {
                customWidth: {
                    item: '20%',
                    price: '15%'
                },
                customAlignment: {
                    price: 'right'
                }
            }
        },
        action: {
            instructions: 'You can check the status of your order and more in your dashboard:',
            button: {
                color: '#3869D4',
                text: 'Go to Dashboard',
                link: 'https://mailgen.js/confirm?s=d9729feb74992cc3482b350163a1a010'
            }
        },
        outro: 'We thank you for your purchase.'
    }
};

var emailBody = mailGenerator.generate(email);
var emailText = mailGenerator.generatePlaintext(email);

It throws the below error

Argument of type '{ body: { name: string; intro: string; table: { data: { item: string; description: string; price: string; }[]; columns: { customWidth: { item: string; price: string; }; customAlignment: { price: string; }; }; }; action: { ...; }; outro: string; }; }' is not assignable to parameter of type 'Content'.
  The types of 'body.table' are incompatible between these types.
    Type '{ data: { item: string; description: string; price: string; }[]; columns: { customWidth: { item: string; price: string; }; customAlignment: { price: string; }; }; }' is not assignable to type 'Table | Table[] | undefined'.
      Type '{ data: { item: string; description: string; price: string; }[]; columns: { customWidth: { item: string; price: string; }; customAlignment: { price: string; }; }; }' is not assignable to type 'Table'.
        Types of property 'columns' are incompatible.
          Type '{ customWidth: { item: string; price: string; }; customAlignment: { price: string; }; }' is missing the following properties from type 'ColumnOptions[]': length, pop, push, concat, and 28 more.

how can I fix this error, thank you

Add 'one click' actions to email subject lines

Incorporate the Gmail schemas to allow users to perform 'one click' tasks such as confirm a subscription or unsubscribe from a list etc.

Published Google documentation for these schemas and functionality are at: https://developers.google.com/gmail/markup/reference/one-click-action

Add RTL support

Make it possible to align the templates to the right.

Should be as simple as adding dir="rtl" to the <html> tag in the themes if rtl: true is set in the Mailgen constructor.

Add two buttons instead of just one

Hi!
I am using mailgen for sending out transactional mails. For a new feature I need two different buttons in one mail. Just tried it out to simply use two action-objects but mailgen seems to just take the second one and ignore the first. Does someone know how to do it?
Cheers

How can we add multi tables into a email?

As the title, I want to add two tables into one email. How can i do?

Outlook

Hi,

I've test your library into oulook and the result is not great :(. The icon size in the header is incorrect and the button in the body is not visible as you can see in the bellow screen :

When i put an svg in logo, nor the logo neither the name is shown.

Language customization

Hi,
Currently it is possible to fully customize the fields to any language. But unfortunately there isn't a way to change that message :

If you're having trouble clicking the "Another language" button, copy and paste the URL below into your web browser.

An idea ?

Remove copyright from plaintext e-mails

Currently, we output the copyright in plaintext e-mails. I think this is invalid, not to mention the fact that it currently contains HTML tags / entities:

Hi John Appleseed,

Welcome to Mailgen! We're very excited to have you on board.

To get started with Mailgen, please click here:
https://mailgen.js/confirm?s=d9729feb74992cc3482b350163a1a010

Need help, or have questions? Just reply to this email, we'd love to help.

Yours truly,
Mailgen

&copy; 2016 <a href="https://mailgen.js/" target="_blank">Mailgen</a>. All rights reserved.

In any case, it is broken. We should either remove it entirely or decode the HTML entities / remove tags.

Any thoughts?

How to customize CSS template

Hello,

I love this project, it's so simple and it reduces a lot the quantity of time I need to setup emails in any of my projects. Thanks 👏.

Although templates provided are enough, sometimes I need to customize it in order to fit with my project style in terms of colors.

For example, maybe the template is using background: #fff but I need to use background: #c9c9c9.

That's nothing mean necessary to create another new template just to replace a color.

Do you think we can establish a mechanism to pass a custom css stylesheet?

I saw that right know CSS is inside HTML and the way to load it is:

var mailGenerator = new Mailgen({
    theme: {
        // Build an absolute path to the theme file within your project
        path: path.resolve('assets/mailgen/theme.html'),
        // Also (optionally) provide the path to a plaintext version of the theme (if you wish to use `generatePlaintext()`)
        plaintextPath: path.resolve('assets/mailgen/theme.txt')
    },
    // Configure your product as usual (see examples above)
    product: {}
});

why not separate it into a different thing, making easy reuse HTML structure but passing custom CSS:

var mailGenerator = new Mailgen({
    theme: {
        indexPath: path.resolve('assets/mailgen/theme.html'),
        stylePath: path.resolve('assets/mailgen/theme.css'),
        plaintextPath: path.resolve('assets/mailgen/theme.txt')
    },
    // Configure your product as usual (see examples above)
    product: {}
});

Thoughts?

greeting: false, // not working

Great work on this by the way!

Setting the greeting to false doesn't remove the greeting. I tried to change it and it is not working either.

feature request: provide raw text version

It would be nice to also provide a raw text version of the generated mail, so that the users don't have to do that theirselves.

add {year}

Hello and congrats for this project; I'm using it as part of https://tom.js.org/ for years 🙂

I noted all my emails footer copyright is outdated because I forgot to update the year.

For solving this, I added {year} as template variable and compile copyright as template before being passed to mailgen:
https://github.com/Kikobeats/tom/pull/270/files#diff-23bf7f84d90195c1f1898d71fc67d20dfd65fa80f9fec24e3e624f552399eb9cR29

I thought that maybe you would to add support for this as parf of the codebase, it could be a simple and great feature.

Align price value to the right.

#18 contains breaking changes to custom themes

PR #18 introduced the ability to add multiple buttons. Despite there being no API changes, sadly this breaks every custom theme out there that uses action.button directly in the templates, like it was used in default and cerberus themes before the update.

We learned this the hard way when a SemVer patch update 1.0.27 broke all of our email related functionality. Not sure what versioning scheme mailgen follows, but as npm relies on packages following SemVer, this should have prompted a SemVer major style bump to 2.0.0.

Solutions for this issue would be either

• Bumping the SemVer so the breaking change wouldn't affect those relying on already working versions

or

• Changing the way #18 is handled so that actions can be arrays or objects internally too.

Cannot read property 'button' of undefined

Commit 4954057 introduced a bug when rendering the html. If no action is passed (or null), it will try to evaluate the element zero. Since we always convert the action to an array, even if it has zero elements (body.action = convertToArray(body.action)). Then the condition locals.action[0].button[0].fallback will try to access the first element of the action that doesn't exist.

After npm install i got 5 high severity vulnerabilities

css-what  <5.0.1
Severity: high
Denial of Service - https://npmjs.com/advisories/1754
fix available via `npm audit fix --force`
Will install [email protected], which is a breaking change
node_modules/css-what
  css-select  <=3.1.2
  Depends on vulnerable versions of css-what
  node_modules/css-select
    cheerio  0.19.0 - 1.0.0-rc.3
    Depends on vulnerable versions of css-select
    node_modules/cheerio
      juice  1.3.4 - 6.0.0
      Depends on vulnerable versions of cheerio
      node_modules/juice
        mailgen  >=1.0.3
        Depends on vulnerable versions of juice
        node_modules/mailgen

5 high severity vulnerabilities

How to embed Images

I am trying to add images, also it will be great if you can help me with adding social media logos in the footer section. Also I have added the Url of the logo but it is not showing are there any set of rules ( Like logo should be png or of any particular size ).

Regards

Missing typescript definition for Product.logoHeigth

Hello,
There is a missing definition for Product.logoHeight in @types. I have submitted a PR for it in definatelyTyped repository, please check. This is my first contribution ever to such big repository, so it might not be great.

DefinitelyTyped/DefinitelyTyped#53345

Best Regards,
Greg

adding and styling product images

I'm trying to add product images to the receipt.
I've tried to add a <img> inside the item property.

data: [
  {
    item: `<img src="${product.image}" style="max-height: 50px;">${product.name}`
  }
];

And the image shows in the email, but the size is different in each email client, probably because not every client recognises the max-height. So is there any correct way to implement product images into the emails?

ps: I love the work you did on this package! Very handy and easy to use.

body.table.columns type

Supposedly ColumnOptions instead of ColumnOptions[]?
https://github.com/eladnava/mailgen/blob/master/index.d.ts#L58

Option to minify html template code.

Whitespace accounts to 50% of the file-size of generated emails. This can quickly add up in queueing systems that notifies thousands of users.
To save CPU cycles, it'd be best to minimize the templates on init, instead of running the minifier on the output, or at render time.

Ideally just after loading it via this.cachedTheme = fs.readFileSync(themePath, 'utf8');.

Huge issues with webpack

Hey there,

I tried using mailgen with webpack in node (for an AWS Lambda function) and it was quite the nightmare :)

Granted, most of the issues were with sub-dependencies such as juice's, but the fact that mailgen caches the theme at runtime from a local file was messing with the paths after compiling via webpack.

I'm not sure if this is something fixable (short of including the default themes in the loaded code itself), but I just wanted to put this out there for anyone else having issues when using webpack.

Thanks for the great work on mailgen so far!

Custom HTML element, or at least image

We have a base64 encoded image, of a qr code that we want to send in the email.
Is it possible to put it inside the body?

Thank you