Power mandrill client for working with templates
npm install powerdrillMandrill with power!
Due to Mandrill's
new pricing
, I will no longer be maintaining this module. If people
want to submit PRs I will likely merge them in, but I will not be actively
working on this as I have moved on to greener pastures.
Mandrill is an awesome email service. Powerdrill makes it
easy to use mandrill and its templates.
The advantages of Mandrill + Powerdrill:
- Easily use mandrill templates, with support for global, and per user variables
- Send an email to thousands of recipients with just one html post request
- Mandrill's open and click reporting, as well as GA integration
- Easy API for Mandrill's metadata (both per user, and per email);
- Easy API for Mandrill's tagging, making it easy to A/B test campaigns
- Easy to register an interceptor for testing purposes
``
npm install powerdrill
Sending an email with the registration template:
`js
var email = require('powerdrill')('myApiKey');
var message = email('registration'); // sets the template
message
.subject('Thanks for registering')
.to('ryan@slingingcode.com')
.send();
`
Or with pure html:
`js
var email = require('powerdrill')('myApiKey');
var message = email();
message
.subject('Thanks for registering')
.to('ryan@slingingcode.com')
.html('
A little more complex:
js
var Message = require('powerdrill').Message;var message = new Message();
message.apiKey('12345')
.subject('Hello world!')
.template('complex-template')
.to('Ryan Schmukler ', {someVariableOnMandrill: true}, {someUserMetaData: user.id()})
.to('John Doe ')
.tag('complex')
.tag('new-style')
.send(function(err, resp) {
console.log(resp);
});
`Complete Documentation
$3
Powerdrill exports a function which helps build messages with an API Key
defined. It returns a
. This helps avoid having to continually type out your api key.`js
var email = require('powerdrill')('myApiKey');var message = email('some-template')
message.subject('Hello world!');
message.to('ryan@slingingcode.com');
message.send();
`is equivalent to:
js
var Message = require('powerdrill').Message;var message = new Message('myApiKey', 'some-template');
// or
var message = new Message();
message.apiKey('myApiKey');
message.template('some-template');
`The purpose of the builder is it allows syntax like:
js
email('some-template')
.subject('Hello world!')
.to('ryan@slingingcode.com')
.send();
`$3
Similarly a builder can set an interceptor (see below) for messages. This can be
useful for development environments.
js
var email = require('powerdrill')('myApiKey', 'ryan@slingingcode.com');
//or
var email = require('powerdrill')('myApiKey');
email.interceptor = 'ryan@slingingcode.com';var message = email('some-template');
message.to('someguy@gmail.com');
message.send() // will send to ryan@slingingcode.com
`$3
A builder can set skip to a default value (useful for testing)
js
var email = require('powerdrill')('myApiKey');
if(process.env.NODE_ENV == 'testing') {
email.skip = true;
}var message = email('some-template');
message.to('someguy@gmail.com');
message.send(); // Wont actually hit the api
`
$3
All of
's configuration methods are chainable, making for highly
readable syntax.#### Constructor(apiKey, template-name)
Returns a new powerdrill instance with specified
apiKey and template. Use of
new keyword is optional.`js
var Message = require('powerdrill').Message;
var messageOne = new Message('123', 'some-template');
var messageTwo = Message('123', 'another-template');
`#### message.apiKey(key)
Sets the apiKey to
. Ret`js
message.apiKey('123');
`#### message.header(key, value)
Sets the header property
to value.If
value is undefined, it clears the header of key property.`js
message.header('Reply-To', 'someperson@somewhere.com');
`#### message.template(template)
Sets the template to
. This should match the template-slug you are
using in Mandrill's templates.`js
message.template('simple-template');
`#### message.templateContent(name, content)
Adds to the
array for dynamic sections.`js
message.template('my-template')
.templateContent('header', 'Hello world
')
.templateContent('body', 'You are so cool
')
.templateContent('footer', 'Sincerely,
Our Team
')
`#### message.html(html)
Switches to
mode. The email will be sent with the html, instead of a
template.`js
message.html('Hello world, from Powerdrill
');
`#### message.text(text)
Switches to
mode. The email will be sent with the text, instead of a
template.`js
message.text('Hello World');
`Additionally, for a multipart message with HTML and plain text, you can add both parts manually.
js
message.html('Hello world
');
message.text('Hello world');
`#### message.subject(subject)
Sets the subject field of the message
js
message.subject('Hello world!');
`#### message.from(address)
Populates the
and from_email fields. address can be in the
following formats:`js
message.from('ryan@slingingcode.com');
// or
message.from('Ryan Schmukler ');
`#### message.to(address, recipientVariables, recipientMetadata)
Adds a recipient. Call multiple times to add multiple recipients.
and recipientMetadata are optional.
See below for other ways to add.simple:
`js
message.to('ryan@slingingcode.com');
`complex:
js
message.to('Ryan Schmukler ', {name: 'Ryan'}, {uid: 123});
`#### message.bcc(address, recipientVariables, recipientMetadata)
Adds a recipient that will be BCC'd.
and recipientMetadata
are optional. See below for other ways to add.js
message.bcc('ryan@slingingcode.com');
`#### message.cc(address, recipientVariables, recipientMetadata)
Adds a recipient that will be CC'd.
and recipientMetadata
are optional. See below for other ways to add.js
message.cc('ryan@slingingcode.com');
`#### message.globalBcc(address)
Add an email that will be BCC'd for all emails send via the message.
js
message.globalBcc('admin@myorganization.com');
`
js
message.cc('ryan@slingingcode.com');
`
$3
Whether or not to track clicks.
js
message.trackClicks(true);
`$3
Whether or not to track opens.
js
message.trackOpens(true);
`$3
Sends the message as configured. Typically the last command called. Calls
where resp is the body returned from the mandrill API.$3
Skips actually sending the message. Useful for testing so that you're not
blasted with emails.
val is optional, but setting it to false will mark it back to not important (default).`js
message.skip() // sets message to skip
message.skip(false) // Restores it to actually sending
`$3
Intercepts emails being sent and sends them to
instead. Useful for
testing that things are working correctly. Will prepend the target address into
the subject line.`js
message.to('bob@gmail.com', {name: 'Bob'});
message.to('steve@gmail.com', {name: 'Steve'});
message.intercept('ryan@slingingcode.com');
message.send();
// Ryan@slingingcode.com will get two emails, each with the specific variables
// for bob and steve
`$3
Adds a tag to the message.
can be an Array of tags or a String for
one tag.`js
message.tag(['cool', 'fun']);
message.tag('easy');
`$3
Sets the message as important, prioritizing it in mandrill's queue.
is optional, but setting it to false will mark it back to not important (default).`js
message.important() // sets message to important
message.important(true) // also sets message to important
message.important(false) // sets message back to not-important
`$3
Tells mandrill to automatically generate the text for the email template at hand.
is optional, but setting it to false will mark it back to not important (default).`js
message.autoText() // enabled autoText
message.autoText(true) // also enables
message.autoText(false) // disables autoText
`$3
Whether you want all recipients to be able to see who else you are sending to.
True by default.
is optional, but setting it to false will mark it back to not important (default).`js
message.preserveRecipients() // enabled preserveRecipients
message.preserveRecipients(true) // also enables
message.preserveRecipients(false) // disables preserveRecipients
`$3
Set merge language to handlebars notation (
). Any other value defaults to mailchimp
notation (| my_var |)`js
message.mergeLanguage('handlebars');
`
$3
Aliased to
.Adds a global merge variable, for use on all emails.
Works with a
key, value syntax or a object syntax.`js
message.globalMergeVar('someVar', 'someValue');
// or
message.globalMergeVar({someVar: someValue});
`$3
Aliased to
.Adds a variable for a specific recipient for use in mandrill's templates. Must specify as an email address, as
per mandrill's API. See
message#to for a shortcut.Takes an object of variables.
`js
message.mergeVar('ryan@slingingcode.com', {name: 'Ryan'});
`$3
Adds metadata for mandrill's use.
Works with a
syntax or a object syntax.`js
message.metadata('someVar', 'someValue');
// or
message.metadata({someVar: someValue});
`$3
Aliased to
.Adds a variable for a specific recipient for use in mandrill's recipient metadata.
See
message#to for a shortcut.Takes an object of variables.
`js
message.userMetadata('ryan@slingingcode.com', {uid: '123456'});
`$3
Mostly internal method. Returns data passsed in to the mandrill API. Useful for
debugging.
$3
Sets the subaccount field of the message
js
message.subaccount('MyMandrillSubaccount');
`$3
Adds an attachment to include in the email. The body should be a base64 encoded string.
js
var fs = require('fs');
var file = fs.readFileSync('test.pdf');
message.attach('application/pdf', 'test.pdf', file.toString('base64'));
`$3
Adds an image to include in-line in the email. The body should be a base64 encoded string.
js
var fs = require('fs');
var image = fs.readFileSync('test.png');
message.image('image/png', 'test.png', image.toString('base64'));
`$3
Sets the time the message should be sent, this accepts any of the formats that a native Date object would.
Note from mandrills documentation
> An additional fee applies for scheduled email, and this feature is only available to accounts with a positive balance
js
message.sendAt('2016-01-01 18:00:00');
`
Planned features
These are some ideas that I have to extend the library. Please open issues to
suggest new features, or to let me know that you'd like a feature on this list:
- More Options (
, trackOpens` etc)