@momsfriendlydevco/email
This module is a thin wrapper around the nodemailer module which loads its config from the locations specified in the Doop project.
Features:
- Object based syntax
- Out-of-the-box compatible with Doop projects and their configuration system
- Includes Nodemailer-Plugin-Inline-Base64 as default to correctly convert Base64 inline to CID attachments
- Template attachment and compiling using Handlebars
Quickstart guide
If you're project is already setup with appropriate config (see Expected Config) you should just be able to call the module as follows:
var email = require('@momsfriendlydevco/email');
email()
.send({
to: 'someone@somewhere.com',
from: 'noreply@domain.com',
subject: 'Plain email test via mfdc-email',
text: 'Hello World',
}, function(err, res) {
// Do something with the result
});
or using chainable methods:
var email = require('@momsfriendlydevco/email');
email()
.to('Joe Random <joe@random.com>')
.subject('HTML chainable method email test via mfdc-email')
.html('<p>Hello <b>World</b></p>')
.send(function(err, res) {
// Do something with the result
});
Debugging
This module uses the Debug NPM. Simply set the environment variable to DEBUG=email
(or any valid enabling glob) to see the output.
> DEBUG=email mocha test/mailgun.js
Mailgun > Send
email Email
email =======================================
email To: matt@mfdc.biz
email Subject: Plain email test via mfdc-email
email -----------------
email Hello Joe
email ------ End ------
email +0ms
Using template views
Specifying the template
property either as a key in the send()
object or via the chainable .template()
method, will specify the file on disk to be used when composing the email.
- The type of email to send is determined by the file extension.
.txt
files are plain text and.html
files are rich content. - All templates are rendered via Mustache with the parameters used taken from the
templateParams
option. - Mustache will automatically escape all variables. If you wish to use an unsecaped variable like a URL encase it in three levels of brackets rather than two e.g.
{{{url}}}
var email = require('@momsfriendlydevco/email');
email()
.to('Joe Random <joe@random.com>')
.subject('Password Recovery')
.template(config.root + '/views/emails/password-recovery.txt')
.templateParams({
name: 'Joe Random',
signoff: 'The MFDC team',
})
.send();
API
send(email, callback)
Dispatch an email. This is as functionally similar to the Nodemailer send()
command as possible. Use this if lower level access is required.
Returns a promise.
to, from, cc, bcc, subject, text, html()
All these methods are chainable:
var email = require('@momsfriendlydevco/email');
email()
.to('someone@somewhere.com')
.subject('something')
.send();
attachments()
Attachments are an array of various inputs including inline file contents, paths to files or streams.
var email = require('@momsfriendlydevco/email');
email()
.to('someone@somewhere.com')
.subject('something')
.attachments([
{filename: 'inline-file.txt', content: 'Hello World!'},
{filename: 'file-on-disk.txt', path: '/tmp/file-on-disk.txt'},
{filename: 'file-from-stream.txt', fs.createReadSteram('/tmp/file-stream.txt')},
{raw: '... mime encoding ...'},
])
.send();
See the NodeMailer attachment specification for more details.
params, templateparams
Populate the Handlebars replacement engine with a given object.
template
Specify a template file to read to obtain the email body. The file extension should be .txt
or .html
to determine the body type.
Specify .params
(or .templateParams
) to populate the Handlebars replacement engine.
var email = require('@momsfriendlydevco/email');
email()
.to('someone@somewhere.com')
.subject('something')
.template('/a/file/somewhere.txt')
.params({username: 'joe'})
.send();
init()
Reinitialize the mail transport and reset all defaults to the global values.
Expected Config
This module expects the following global.config
/ global.app.config
variables to be specified to operate:
Method | Key | Type | Description |
---|---|---|---|
All | email.enabled |
Boolean | Temporarily disable the sending of email. If falsy this will message to the console and not actually send anything |
email.method |
String | What transport profile to use, see init() for details |
|
email.{to,from,subject,cc,bcc} |
String / Array | Default fields to use if unspecified | |
email.template |
String | Read a template file and render it as the email content | |
email.inlineBase64 |
Boolean | Automatically convert base64 blob to cid attachment + ref | |
Mailgun | mailgun.apiKey |
String | The API key for the Mailgun profile |
mailgun.domain |
String | The Mailgun domain, usually something like 'acme.com' (no 'http://' prefix or Mailgun suffix) | |
Outlook365 | outlook365.user |
String | User auth to send emails as via Outlook365 |
outlook365.pass |
String | User pass to send emails as via Outlook365 | |
smtp.host |
String | Hostname to send via with SMTP | |
smtp.port |
String | Port to send via with SMTP | |
smtp.secure |
Boolean | Whether the connection should use TLS | |
SMTP | smtp.user |
String | User auth to send emails as via SMTP |
smtp.pass |
String | User pass to send emails as via SMTP |