ultrases

Dead simple email dispatch with AWS SES (Amazon Simple Email Service) with templates!

Getting Started

Install the module via npm with: npm install ultrases

var UltraSES = require('ultrases');
var mailer = new UltraSES({...});

Why?

"We already have the AWS SDK for Node, why do we need another module?"

Because the official AWS SDK for Node.js is cumbersome and stuffy. Not to mention those 4 level deep configuration objects. Besides, it prompotes uppercasing the first letter of properties!

  var params = {WhoEvenDoesThat: 'nobody... except amazon'}

UltraSES is a high level "abstraction" - no overkill.

Documentation

Quick Reference:

• Setup
• Sending a Simple Email
• Sending Raw HTML
• Sending a Jade Template
• One Last Thing

Setup

Start by creating a new instance of UltraSES. Pass your access key for AWS in this fashion:

var mailer = new UltraSES({
  aws: {
    accessKeyId: 'LOOKATHESEUPERCASELETTERANDNUMBERS123',
    secretAccessKey: 'shhhh+its/asecrettttttttt+42'
  }
}

Alternatively, you may pass a "pre-initialized" AWS SDK object like so:

var aws = require('aws-sdk');
AWS.config.update({...});
var mailer = new UltraSES({sdk: aws});

You can even pass in an initialized SES client object:

var ses = new aws.SES();
var mailer = new UltraSES({client: ses});

You can also supply defaults for sending emails (for example, the "source" address)

var mailer = new UltraSES({
  aws: {...},
  defaults: { from: 'Team Octocat <octo@octoland.com>' }
}

You can always override these defaults when you send the actual emails, of course.

Keep in mind that the parameters you give to various methods adhere to the principles in the AWS SDK for Node. You can pass an array instead of a string for multiple recipients, specify a ReplyTo and ReturnPath address, specify character encodings, and so on.

Sending a Simple Email

The basic method for sending email is mailer.sendText(email, text, done) and it takes (as you can probably see), 3 arguments:

var email = {to: 'hexacat@hexaland.com', subject: 'Hello from Octoland!'};
mailer.sendText(email, 'Look at this fantastic email body!', function(err){
    if(err) throw err;
    console.log('email sent!');
  });

Some notes:

• The emails will be sent from octo@octoland.com, because we set that as a default during initialization.
• You may include the message body in the "email" object instead of as an extra argument var email = {subject: '...', text: '..'})
• You may send an email to multiple recipients by passing in an array instead of a string to to, as well as provide BCC and CC recipients.

Sending Raw HTML

UltraSES provides a simple wrapper for sending HTML emails. The cool thing about this is that it automatically creates a text version of your HTML for simpler email clients, using html-to-text.

var email = { from: 'quadrocat@quadworld.com', to: 'htmlcat@hexaland.com', subject: 'Look at this pretty formatting!' };
mailer.sendHTML(email, '<h1>Why hello there</h1>', function(err){
  if(err) throw err;
  console.log('html email sent!');
});

• In this example, we overrode the "from" address that we set during initialization.

Sending a Jade Template

Jade is one of the most popular templating engines for Node. UltraSES comes with out of the box support for compiling Jade templates with your "locals" and sending them.

var email = { to: 'htmlcat@hexaland.com', subject: 'Now that\'s a pretty email' };
var template = { file: './path/to/template.jade', locals: { some: 'local', variables: 'here' } };
mailer.sendTemplate(email, template, function(err){
  if(err) throw err;
  console.log('compiled template email sent');
})

• If you already have compiled template file, just pass it to mailer.sendHTML.
• You may pass the contents of Jade template instead of the file path, by using the property contents instead of file:

var template = { contents: ('html' + '\n\t' + 'body' + '\n\t\t' + 'h1 ' + 'Oh, it\'s you again') };

One Last Thing

UltraSES exposes it's internal SES client as provided by the AWS SDK under the property ses, so you can do things like:

mailer.ses.setIdentityFeedbackForwardingEnabled({ForwardingEnabled: true, Identity: 'WhatIsUpWithThese@UpperCaseLetters.com'}, function(err, data){}), 

Contributing

Honestly, this module doesn't have much room to grow. It does what it does and aside for bugs (and maybe customizable template engine support?) there isn't much to expand. If you have some cool ideas though, go ahead and do a pull request, or create an issue with your idea!

It's just email, after all. This is '90s technology we're dealing with.

Here is something else I've realized - it's practically impossible to write unit tests for a module that sends email.

Release History

The latest version is always on npm. You can see the tagged versions here or view the commits here.

License

Copyright (c) 2014 Yotam Tanay. Licensed under the MIT license.