<div align="center">

sendemail 💌

Effortlessly send email from any Node.js App using Amazon's Simple Email Service (SES). <br /> e.g: welcome, newsletter, verification, password reset and notification emails

</div> <br />

Why? 🤷

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.

What? 💭

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.

Decisions We Made (to Get Started as Fast as Possible)

In crafting this module (for our own use) we have made a few of technical decisions (for pragmatic reasons):

1. use environment variables for storing sensitive information (API Keys) and projects-specific configuration (Template Directory)
2. use Amazon Web Services Simple Email Service ("AWS SES") for reliably sending email messages because it has good documentation, excellent "deliverability" and no minimum spend (10 cents per 1000 emails sent)! (there's also a generous "Free Tier" of 65k emails per month if you're new to AWS)
3. use Handlebars for email template rendering. Handlebars is very easy to use and allows us to send beautiful HTML emails without the complexity or learning curve of many other view libraries.

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.

How? ✅

Checklist (everything you need to get started in 5 minutes)

• [ ] install the sendemail module from NPM
• [ ] Ensure that you have an AWS Account and have downloaded your credentials.
• [ ] set the required environment variable (see below)
• [ ] If you don't already have a /templates directory in your project create one!
• [ ] create a pair of email templates in your /templates directory one called hello.txt the other hello.html
• [ ] borrow the code for hello.txt and hello.html from the /examples/templates directory of this project!
• [ ] create a file called welcome.js and paste some sample code in it (see: /examples/templates/send-welcome-email.js )

1. Install sendemail from NPM 📦

npm install sendemail --save

2. Set your Environment Variables 🔐

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.

2.1 Verify Your Email Address on AWS SES

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?

2.2 Create an .env File

Once 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

3. Create your Template(s) 📝

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/

4. Send an Email! ✉️

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(' - - - - - - - - - - - - - - - - - - - - - - - - - - - -')
})

Result:

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.

More Options?:

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);

<br /> ___

Notes?

Which Email Service Provider?

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)

Moving out of AWS SES sandbox environment.

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'.

### Which View/Template Libaray?

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 (*signific