11 |
12 | > These e-mails were generated using the built-in `salted` theme.
13 |
14 | ## Usage
15 |
16 | First, install the package using npm:
17 |
18 | ```shell
19 | npm install mailgen --save
20 | ```
21 |
22 | Then, start using the package by importing and configuring it:
23 |
24 | ```js
25 | var Mailgen = require('mailgen');
26 |
27 | // Configure mailgen by setting a theme and your product info
28 | var mailGenerator = new Mailgen({
29 | theme: 'default',
30 | product: {
31 | // Appears in header & footer of e-mails
32 | name: 'Mailgen',
33 | link: 'https://mailgen.js/'
34 | // Optional product logo
35 | // logo: 'https://mailgen.js/img/logo.png'
36 | }
37 | });
38 | ```
39 |
40 | Next, generate an e-mail using the following code:
41 |
42 | ```js
43 | var email = {
44 | body: {
45 | name: 'John Appleseed',
46 | intro: 'Welcome to Mailgen! We\'re very excited to have you on board.',
47 | action: {
48 | instructions: 'To get started with Mailgen, please click here:',
49 | button: {
50 | color: '#22BC66', // Optional action button color
51 | text: 'Confirm your account',
52 | link: 'https://mailgen.js/confirm?s=d9729feb74992cc3482b350163a1a010'
53 | }
54 | },
55 | outro: 'Need help, or have questions? Just reply to this email, we\'d love to help.'
56 | }
57 | };
58 |
59 | // Generate an HTML email with the provided contents
60 | var emailBody = mailGenerator.generate(email);
61 |
62 | // Generate the plaintext version of the e-mail (for clients that do not support HTML)
63 | var emailText = mailGenerator.generatePlaintext(email);
64 |
65 | // Optionally, preview the generated HTML e-mail by writing it to a local file
66 | require('fs').writeFileSync('preview.html', emailBody, 'utf8');
67 |
68 | // `emailBody` now contains the HTML body,
69 | // and `emailText` contains the textual version.
70 | //
71 | // It's up to you to send the e-mail.
72 | // Check out nodemailer to accomplish this:
73 | // https://nodemailer.com/
74 | ```
75 |
76 | This code would output the following HTML template:
77 |
78 | 
79 |
80 | ## More Examples
81 |
82 | * [Receipt](examples/receipt.js)
83 | * [Password Reset](examples/reset.js)
84 |
85 | ## Plaintext E-mails
86 |
87 | To generate a [plaintext version of the e-mail](https://litmus.com/blog/best-practices-for-plain-text-emails-a-look-at-why-theyre-important), simply call `generatePlaintext()`:
88 |
89 | ```js
90 | // Generate plaintext email using mailgen
91 | var emailText = mailGenerator.generatePlaintext(email);
92 | ```
93 |
94 | ## Supported Themes
95 |
96 | The following open-source themes are bundled with this package:
97 |
98 | * `default` by [Postmark Transactional Email Templates](https://github.com/wildbit/postmark-templates)
99 |
100 | 
101 |
102 | * `neopolitan` by [Send With Us](https://github.com/sendwithus/templates/tree/master/templates/neopolitan)
103 |
104 | 
105 |
106 | * `salted` by [Jason Rodriguez](https://github.com/rodriguezcommaj/salted)
107 |
108 | 
109 |
110 | * `cerberus` by [Ted Goas](http://tedgoas.github.io/Cerberus/)
111 |
112 | 
113 |
114 | We thank the contributing authors for creating these themes.
115 |
116 | ## Custom Themes
117 |
118 | If you want to supply your own custom theme or add a new built-in theme, check out [THEME.md](THEME.md) for instructions.
119 |
120 | ## RTL Support
121 |
122 | To change the default text direction (left-to-right), simply override it as follows:
123 |
124 | ```js
125 | var mailGenerator = new Mailgen({
126 | theme: 'salted',
127 | // Custom text direction
128 | textDirection: 'rtl',
129 | });
130 | ```
131 |
132 | ## Custom Logo Height
133 |
134 | To change the default product logo height, set it as follows:
135 |
136 | ```js
137 | var mailGenerator = new Mailgen({
138 | product: {
139 | // Custom product logo URL
140 | logo: 'https://mailgen.js/img/logo.png',
141 | // Custom logo height
142 | logoHeight: '30px'
143 | }
144 | });
145 | ```
146 |
147 | ## Language Customizations
148 |
149 | To customize the e-mail greeting (Hi) or signature (Yours truly), supply custom strings within the e-mail `body`:
150 |
151 | ```js
152 | var email = {
153 | body: {
154 | greeting: 'Dear',
155 | signature: 'Sincerely'
156 | }
157 | };
158 | ```
159 |
160 | To not include the signature or greeting at all, set the signature or greeting fields to `false`:
161 |
162 | ```js
163 | var email = {
164 | body: {
165 | signature: false,
166 | greeting: false // This will override and disable name & title options
167 | }
168 | };
169 | ```
170 |
171 | To use a custom title string rather than a greeting/name introduction, provide it instead of `name`:
172 |
173 | ```js
174 | var email = {
175 | body: {
176 | // Title will override `name`
177 | title: 'Welcome to Mailgen!'
178 | }
179 | };
180 | ```
181 |
182 | To customize the `copyright`, override it when initializing `Mailgen` within your `product` as follows:
183 |
184 | ```js
185 | // Configure mailgen
186 | var mailGenerator = new Mailgen({
187 | theme: 'salted',
188 | product: {
189 | name: 'Mailgen',
190 | link: 'https://mailgen.js/',
191 | // Custom copyright notice
192 | copyright: `Copyright © ${new Date().getFullYear()} Mailgen. All rights reserved.`,
193 | }
194 | });
195 | ```
196 |
197 | ## Multiline Support
198 |
199 | To inject multiple lines of text for the `intro` or `outro`, simply supply an array of strings:
200 |
201 | ```js
202 | var email = {
203 | body: {
204 | intro: ['Welcome to Mailgen!', 'We\'re very excited to have you on board.'],
205 | outro: ['Need help, or have questions?', 'Just reply to this email, we\'d love to help.'],
206 | }
207 | };
208 | ```
209 |
210 | ## Elements
211 |
212 | Mailgen supports injecting custom elements such as dictionaries, tables and action buttons into e-mails.
213 |
214 | ### Action
215 |
216 | To inject an action button in to the e-mail, supply the `action` object as follows:
217 |
218 | ```js
219 | var email = {
220 | body: {
221 | action: {
222 | instructions: 'To get started with Mailgen, please click here:',
223 | button: {
224 | color: '#48cfad', // Optional action button color
225 | text: 'Confirm your account',
226 | link: 'https://mailgen.js/confirm?s=d9729feb74992cc3482b350163a1a010'
227 | }
228 | }
229 | }
230 | };
231 | ```
232 |
233 | To inject multiple action buttons in to the e-mail, supply the `action` object as follows:
234 |
235 | ```js
236 | var email = {
237 | body: {
238 | action: [
239 | {
240 | instructions: 'To get started with Mailgen, please click here:',
241 | button: {
242 | color: '#22BC66',
243 | text: 'Confirm your account',
244 | link: 'https://mailgen.js/confirm?s=d9729feb74992cc3482b350163a1a010'
245 | }
246 | },
247 | {
248 | instructions: 'To read our frequently asked questions, please click here:',
249 | button: {
250 | text: 'Read our FAQ',
251 | link: 'https://mailgen.js/faq'
252 | }
253 | }
254 | ]
255 | }
256 | };
257 | ```
258 |
259 | You can enable a fallback link and instructions for action buttons in case e-mail clients don't render them properly. This can be achieved by setting `button.fallback` to `true`, or by specifying custom fallback text as follows:
260 | ```js
261 | var email = {
262 | body: {
263 | action: [
264 | {
265 | instructions: 'To get started with Mailgen, please click here:',
266 | button: {
267 | color: '#22BC66',
268 | text: 'Confirm your account',
269 | link: 'https://mailgen.js/confirm?s=d9729feb74992cc3482b350163a1a010',
270 | fallback: true
271 | }
272 | },
273 | {
274 | instructions: 'To read our frequently asked questions, please click here:',
275 | button: {
276 | text: 'Read our FAQ',
277 | link: 'https://mailgen.js/faq',
278 | fallback: {
279 | text: 'This is my custom text for fallback'
280 | }
281 | }
282 | }
283 | ]
284 | }
285 | };
286 | ```
287 |
288 | ### Table
289 |
290 | To inject a table into the e-mail, supply the `table` object as follows:
291 |
292 | ```js
293 | var email = {
294 | body: {
295 | table: {
296 | data: [
297 | {
298 | item: 'Node.js',
299 | description: 'Event-driven I/O server-side JavaScript environment based on V8.',
300 | price: '$10.99'
301 | },
302 | {
303 | item: 'Mailgen',
304 | description: 'Programmatically create beautiful e-mails using plain old JavaScript.',
305 | price: '$1.99'
306 | }
307 | ],
308 | columns: {
309 | // Optionally, customize the column widths
310 | customWidth: {
311 | item: '20%',
312 | price: '15%'
313 | },
314 | // Optionally, change column text alignment
315 | customAlignment: {
316 | price: 'right'
317 | }
318 | }
319 | }
320 | }
321 | };
322 | ```
323 |
324 | To inject multiple tables into the e-mail, supply the `table` property with an array of objects as follows:
325 |
326 | ```js
327 | var email = {
328 | body: {
329 | table: [
330 | {
331 | // Optionally, add a title to each table.
332 | title: 'Order 1',
333 | data: [
334 | {
335 | item: 'Item 1',
336 | description: 'Item 1 description',
337 | price: '$1.99'
338 | },
339 | {
340 | item: 'Item 2',
341 | description: 'Item 2 description',
342 | price: '$2.99'
343 | }
344 | ],
345 | columns: {
346 | // Optionally, customize the column widths
347 | customWidth: {
348 | item: '20%',
349 | price: '15%'
350 | },
351 | // Optionally, change column text alignment
352 | customAlignment: {
353 | price: 'right'
354 | }
355 | }
356 | },
357 | {
358 | // Optionally, add a title to each table.
359 | title: 'Order 2',
360 | data: [
361 | {
362 | item: 'Item 1',
363 | description: 'Item 1 description',
364 | price: '$2.99'
365 | },
366 | {
367 | item: 'Item 2',
368 | description: 'Item 2 description',
369 | price: '$1.99'
370 | }
371 | ],
372 | columns: {
373 | // Optionally, customize the column widths
374 | customWidth: {
375 | item: '20%',
376 | price: '15%'
377 | },
378 | // Optionally, change column text alignment
379 | customAlignment: {
380 | price: 'right'
381 | }
382 | }
383 | }
384 | ]
385 | }
386 | };
387 | ```
388 |
389 | > Note: Tables are currently not supported in plaintext versions of e-mails.
390 |
391 | ### Dictionary
392 |
393 | To inject key-value pairs of data into the e-mail, supply the `dictionary` object as follows:
394 |
395 | ```js
396 | var email = {
397 | body: {
398 | dictionary: {
399 | date: 'June 11th, 2016',
400 | address: '123 Park Avenue, Miami, Florida'
401 | }
402 | }
403 | };
404 | ```
405 |
406 | ## Go-To Actions
407 |
408 | You can make use of Gmail's [Go-To Actions](https://developers.google.com/gmail/markup/reference/go-to-action) within your e-mails by suppling the `goToAction` object as follows:
409 |
410 | ```js
411 | var email = {
412 | body: {
413 | // Optionally configure a Go-To Action button
414 | goToAction: {
415 | text: 'Go to Dashboard',
416 | link: 'https://mailgen.com/confirm?s=d9729feb74992cc3482b350163a1a010',
417 | description: 'Check the status of your order in your dashboard'
418 | }
419 | }
420 | };
421 | ```
422 |
423 | > Note that you need to [get your sender address whitelisted](https://developers.google.com/gmail/markup/registering-with-google) before your Go-To Actions will show up in Gmail.
424 |
425 | ## Troubleshooting
426 |
427 | 1. After sending multiple e-mails to the same Gmail / Inbox address, they become grouped and truncated since they contain similar text, breaking the responsive e-mail layout.
428 |
429 | > Simply sending the `X-Entity-Ref-ID` header with your e-mails will prevent grouping / truncation.
430 |
431 | ## Contributing
432 |
433 | Thanks so much for wanting to help! We really appreciate it.
434 |
435 | * Have an idea for a new feature?
436 | * Want to add a new built-in theme?
437 |
438 | Excellent! You've come to the right place.
439 |
440 | 1. If you find a bug or wish to suggest a new feature, please create an issue first
441 | 2. Make sure your code & comment conventions are in-line with the project's style
442 | 3. Make your commits and PRs as tiny as possible - one feature or bugfix at a time
443 | 4. Write detailed commit messages, in-line with the project's commit naming conventions
444 |
445 | > Check out [THEME.md](THEME.md) if you want to add a new built-in theme to Mailgen.
446 |
447 | ## License
448 |
449 | Apache 2.0
450 |
--------------------------------------------------------------------------------
/THEME.md:
--------------------------------------------------------------------------------
1 | # Theming Instructions
2 |
3 | This file contains instructions on adding themes to Mailgen:
4 |
5 | * [Using a Custom Theme](#using-a-custom-theme)
6 | * [Creating a Built-In Theme](#creating-a-built-in-theme)
7 |
8 | > We use [ejs](http://ejs.co/) under the hood to inject the e-mail body into themes.
9 |
10 | ## Using a Custom Theme
11 |
12 | If you want to supply your own **custom theme** for Mailgen to use (but don't want it included with Mailgen):
13 |
14 | 1. Create an `.html` file within your project directory
15 | 2. Paste your e-mail template into the file
16 | 3. Scroll down to the [injection snippets](#injection-snippets) and copy and paste each code snippet into the relevant area of your template markup
17 | 4. Optionally create a `.txt` file for the plaintext version of your theme (base off of [`themes/default/index.txt`](themes/default/index.txt))
18 |
19 | When you've got your custom theme file(s) ready, apply them as follows:
20 |
21 | ```js
22 | var path = require('path');
23 | var Mailgen = require('mailgen');
24 |
25 | // Configure mailgen by providing the path to your custom theme
26 | var mailGenerator = new Mailgen({
27 | theme: {
28 | // Build an absolute path to the theme file within your project
29 | path: path.resolve('assets/mailgen/theme.html'),
30 | // Also (optionally) provide the path to a plaintext version of the theme (if you wish to use `generatePlaintext()`)
31 | plaintextPath: path.resolve('assets/mailgen/theme.txt')
32 | },
33 | // Configure your product as usual (see examples above)
34 | product: {}
35 | });
36 | ```
37 |
38 | # Creating a Built-In Theme
39 |
40 | If you want to create a new **built-in** Mailgen theme:
41 |
42 | 1. Fork the repository to your GitHub account and clone it to your computer
43 | 2. Create a new directory inside `themes` with the desired theme name
44 | 3. Create an `index.html` file and an `index.txt` file within your theme directory
45 | 4. Copy the contents of [`themes/default/index.txt`](themes/default/index.txt) to your `index.txt` file and make any necessary changes
46 | 5. Paste your custom template HTML into the `index.html` file you created
47 | 6. Scroll down to the [injection snippets](#injection-snippets) and copy and paste each code snippet into the relevant area of your template markup
48 | 7. Test the theme by running the `examples/*.js` scripts (insert your theme name in each script) and observing the template output in `preview.html`
49 | 8. Take a screenshot of your theme portraying each example and place it in `screenshots/{theme}/{example}.png`
50 | 9. Add the theme name, credit, and screenshots to the `README.md` file's [Supported Themes](README.md#supported-themes) section (copy one of the existing themes' markup and modify it accordingly)
51 | 7. Submit a pull request with your changes and we'll let you know if anything's missing!
52 |
53 | Thanks again for your contribution!
54 |
55 | # Injection Snippets
56 |
57 | ## Product Branding Injection
58 |
59 | The following will inject either the product logo or name into the template.
60 |
61 | ```html
62 |
63 | <% if (locals.product.logo) { %>
64 | <% if (locals.product.logoHeight) { %>
65 | <%- introItem %>
99 | <% }) -%> 100 | <% } %> 101 | ``` 102 | 103 | ## Dictionary Injection 104 | 105 | The following will inject a `|
152 | width="<%= table.columns.customWidth[column] %>"
153 | <% } %>
154 | <% if(locals.table.columns && locals.table.columns.customAlignment && locals.table.columns.customAlignment[column]) { %>
155 | style="text-align:<%= table.columns.customAlignment[column] %>"
156 | <% } %>
157 | >
158 | <%- column.charAt(0).toUpperCase() + column.slice(1) %> 159 | |
160 | <% } %>
161 |
|---|
| 167 | style="text-align:<%= table.columns.customAlignment[column] %>" 168 | <% } %> 169 | > 170 | <%- table.data[i][column] %> 171 | | 172 | <% } %> 173 |
<%- actionItem.instructions %>
219 | 220 | <%- actionItem.button.text %> 221 | 222 | <% }) -%> 223 | <% } %> 224 | ``` 225 | 226 | It's a good idea to add this to the top of the template to specify a fallback color for the action buttons in case it wasn't provided by the user: 227 | 228 | ```html 229 | <% 230 | if (locals.action) { 231 | // Make it possible to override action button color (specify fallback color if no color specified) 232 | locals.action.forEach(function(actionItem) { 233 | if (!actionItem.button.color) { 234 | actionItem.button.color = '#48CFAD'; 235 | } 236 | }); 237 | } 238 | %> 239 | ``` 240 | 241 | ## Outro Injection 242 | 243 | The following will inject the outro text (string or array) into the e-mail: 244 | 245 | ```html 246 | <% if (locals.outro) { %> 247 | <% outro.forEach(function (outroItem) { -%> 248 |<%- outroItem %>
249 | <% }) -%> 250 | <% } %> 251 | ``` 252 | 253 | ## Signature Injection 254 | 255 | The following will inject the signature phrase (e.g. Yours truly) along with the product name into the e-mail: 256 | 257 | ```html 258 | <%- signature %>, 259 |
257 | 258 | <%- title %> 259 |260 | |
261 | |||
268 |
|
329 | |||
333 |
|
374 | |||
381 |
|
402 |
|
411 |
412 | <% action.forEach(function (actionItem) { -%>
413 | <% actionItem.button.forEach(function (actionButton) { -%>
414 | <% if (actionButton.fallback != null) { %>
415 |
416 | <%- actionButton.fallback.text %> |
423 |
| 431 | <%- product.copyright %> 432 | | 433 |
244 |
|
435 | ||||||||||||
177 |
|
381 |
|
221 |
222 |
255 |
|
256 |
263 |
|
345 |
352 |
|
412 | ||||||||
|
417 | 418 |
|
435 | ||||||||
440 |
|
458 |