While we would prefer for email to be phased out and replaced by something better, the fact remains that most people still use email as their primary means of (digital) communication.
Given that email is not going away, we need to make sending email to people as simple and reliable as possible.
Reliably Send beautiful email with dependable delivery. When email that has to get through as quickly as possible so everyone can get on with their lives.
In crafting this module (for our own use) we have made a few of technical decisions (for pragmatic reasons):
Note: if you prefer to use a different Email Service provider or template/view library for your project, please let us know! We are happy to support alternatives to make this project more useful to other people with specific needs.
sendemail
module from NPMhello.txt
the other hello.html
hello.txt
and hello.html
from the /examples/templates directory of this project!welcome.js
and paste some sample
code in it (see: [/examples/templates/send-welcome-email.js]() )sendemail
from NPM 📦npm install sendemail --save
sendemail
requires you set
five environment variables.
The first 4 relate to your AWS account
The TEMPLATE_DIRECTORY
should contain your email
templates.
We recommend using
env2
to load your Environment Variables from a file so that you can easily keep track of which variables you are using in each environment.
In order to send email from a specific email address, you will need to verify that email address on AWS SES. The process is quite simple, but there are a few steps involved, so we created a separate step-by-step guide: How to setup AWS SES verified email?
.env
FileOnce you have a verified email on AWS SES,
create a file in the root of your project called .env
and paste the following:
export AWS_REGION=eu-west-1
export AWS_ACCESS_KEY_ID=YOURKEY
export AWS_SECRET_ACCESS_KEY=YOURSUPERSECRET
export SENDER_EMAIL_ADDRESS=aws.verified.email@dwyl.com
export TEMPLATE_DIRECTORY=./examples/templates
Update the values to the real ones for your AWS account.
If you are new to environment variables, we have a quick introduction: https://github.com/dwyl/learn-environment-variables
Create a pair of templates simple .html
(pretty design) and .txt
(plaintext) templates to get started.
Here's what our pair of templates look like side-by-side:
[ Click the image to expand/zoom ]
Question: Should we create plaintext templates (in addition to html?)? Quick Answer: Yes. For Expanded Answer, see: Plain Text Templates? section in Notes (below).
If you are stuck, have a look at /examples/templates/
Create a file called email.js
and paste the following:
var sendemail = require('sendemail')
var email = sendemail.email;
var person = {
name : "Jenny",
email: "your.name+test" + Math.random() + "@gmail.com", // person.email can also accept an array of emails
subject:"Welcome to DWYL :)"
}
email('welcome', person, function(error, result){
console.log(' - - - - - - - - - - - - - - - - - - - - -> email sent: ');
console.log(result);
console.log(' - - - - - - - - - - - - - - - - - - - - - - - - - - - -')
})
For full code of working example see: /examples/templates/send-welcome-email.js Note: you still need to set your environment variables for the email to be sent.
If you wish to send to multiple recipients of include CC or BCC recipients,
use the sendMany method. This allows you to provide an options object
with an array of toAddresses
, ccAddresses
, and bccAddresses
and charset options.
e.g.
var sendemail = require('sendemail');
var options = {
templateName: 'hello',
context: {
tempalateVariableName: 'Variable Value',
name: 'Joe Bloggs'
},
subject: 'Welcome to Email',
senderEmailAddress: 'From Name <from@gmail.com>',
toAddresses: ['recipient1@gmail.com', 'recipient2@gmail.com'],
ccAddresses: ['ccRecipient1@gmail.com', 'ccRecipient2@gmail.com'],
bccAddresses: ['bccRecipient1@gmail.com', 'bccRecipient2@gmail.com'],
htmlCharset: 'utf16',
textCharset: 'utf16',
subjectCharset: 'utf8'
};
sendemail.sendMany(options, callback);
We are currently using AWS SES for dwyl.
If you want to use an alternative mail sender, e.g: sendgrid or mailgun please tell us: https://github.com/dwyl/sendemail/issues (we are always happy to help)
When you first sign up to AWS, you are provided with a sandbox account. With this, you can send up to 200 emails a day, to email addresses that you have registered on your sandbox environment. For some use cases this is fine, but for those who want a higher daily sending quota, want to send emails without the restriction of registering recipient emails upfront, amongst other reasons 'moving out' of your sandbox might be beneficial. For many services, this upgrade comes with a cost, but with AWS SES, this is not necessarily the case. A quick and easy way to do so is to apply for an increase in your SES Sending Limit; (1) click on the following link, https://aws.amazon.com/ses/faqs/ (2) search for "apply" in section 4 and (3) click 'apply'.
For simplicity we are using
Handlebars,
handlebars is tried and tested and while it does not attempt
to do anything fancy ("VirtualDOM"), it does allow
you to do sophisticated templates with includes and iterators
and supports compilation so its fast
(fast enough ... how many millions of emails are you sending per day...?)
Yes... mustache is "faster"
than handlebars ... but in our experience having conditionals
(i.e. "logic") is very useful for reducing the number of required templates while not (significantly) increasing complexity.
we don't think if
statements in views are a "crime" ... do you...?
If anyone feels strongly about switching to an alternative template engine, please raise an issue: https://github.com/dwyl/sendemail/issues (please give clear reasons, i.e. not "react-ify-licious-heah because its so cool ... ")
In our experience, while most modern email clients
(Gmail, Apple/iOS Mail, Yahoo! Mail, Outlook)
have HTML
email enabled by default,
often the people who prefer text-only
(e.g: people with Blackberry phones,
visual/physical impairment or company email
email systems - with aggressive filtering)
are "higher value" customers. Also,
possibly more importantly (depending on who is using your product/service) you can have technical privacy-concious people
that only read .txt
email to avoid sending
and tracking data ... but, if you're building a tool for
non-technical people, focus on the fact that .txt
email
is more accessible and prevents your messages getting
blocked by spam filters.
When testing functions which will subsequently call methods in third party libraries, your tests no longer need to run through those methods, you can instead assume that the third party method will give back what they say they will give back (since these tests should already exist in the library you are using).
Once you are sure there are sufficient tests in place for the method you will stub, you may proceed with a test double.
For this library there are significant benefits for using a test double for the email
method (see #49).
If you have a helper function notifyUser
which will subsequently call require('sendemail').email
, this can be stubbed with:
npm install --save-dev sinon
Changing your test:
var notifyUser = require('./notifyUser.js');
test('"notifyUser" should return the object { message: "email sent" }', function (t) {
notifyUser('Bob', function (err, res) {
t.deepEqual(res, { message: 'email sent' });
t.end();
});
});
To be something like this:
var notifyUser = require('./notifyUser.js'); // this has to be required before the stub is implemented
var sinon = require('sinon');
var sendemail = require('sendemail');
test('"notifyUser" should return the object { message: "email sent", error: null }', function (t) {
var email = sinon.stub(sendemail, 'email', function (name, person, cb) {
cb(null, { message: 'email sent', anyotherkeywecareabout: 'value' });
});
notifyUser('Bob', function (err, res) {
email.restore();
t.ok(email.calledWith('Bob'));
t.deepEqual(res, { message: 'email sent' });
t.end();
});
});
Check out the article in background reading for best practices when implementing test doubles with sinon
There are many situations where you want to send people email.
A simple "hello & welcome to our community" email you send to people when they register to learn more about your product/service. see: /examples/templates/send-welcome-email.js
As part of registering new people for your app you will need to verify their email addresses to ensure that people are not signing up with fake emails (or worse using someone else's email!)
People forget passwords, we need to help them set a new password as quickly & securely as possible.
Remind people they signed up but have not used the product/service?
Sam liked your post/photo/update ... social validation that your life has meaning! 😉