Dead simple email dispatch with AWS SES (Amazon Simple Email Service)
npm install ultrasesnpm install ultrases
javascript
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!
`javascript
var params = {WhoEvenDoesThat: 'nobody... except amazon'}
`
UltraSES is a high level "abstraction" - no overkill.
Documentation
$3
- Setup
- Sending a Simple Email
- Sending Raw HTML
- Sending a Jade Template
- One Last Thing
$3
Start by creating a new instance of UltraSES. Pass your access key for AWS in this fashion:
`javascript
var mailer = new UltraSES({
aws: {
accessKeyId: 'LOOKATHESEUPERCASELETTERANDNUMBERS123',
secretAccessKey: 'shhhh+its/asecrettttttttt+42'
}
}
`
Alternatively, you may pass a "pre-initialized" AWS SDK object like so:
`javascript
var aws = require('aws-sdk');
AWS.config.update({...});
var mailer = new UltraSES({sdk: aws});
`
You can even pass in an initialized SES client object:
`javascript
var ses = new aws.SES();
var mailer = new UltraSES({client: ses});
`
You can also supply defaults for sending emails (for example, the "source" address)
`javascript
var mailer = new UltraSES({
aws: {...},
defaults: { from: 'Team Octocat ' }
}
`
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.
$3
The basic method for sending email is `mailer.sendText(email, text, done)` and it takes (as you can probably see), 3 arguments:
`javascript
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.
$3
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.
`javascript
var email = { from: 'quadrocat@quadworld.com', to: 'htmlcat@hexaland.com', subject: 'Look at this pretty formatting!' };
mailer.sendHTML(email, 'Why hello there
', function(err){
if(err) throw err;
console.log('html email sent!');
});
`
+ In this example, we overrode the "from" address that we set during initialization.
$3
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.
`javascript
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:
`javascript
var template = { contents: ('html' + '\n\t' + 'body' + '\n\t\t' + 'h1 ' + 'Oh, it\'s you again') };
`
$3
UltraSES exposes it's internal SES client as provided by the AWS SDK under the property ses, so you can do things like:
`javascript
mailer.ses.setIdentityFeedbackForwardingEnabled({ForwardingEnabled: true, Identity: 'WhatIsUpWithThese@UpperCaseLetters.com'}, function(err, data){}),
``