Test email functionality in Node.js with Guerilla Mail

Published on September 30, 2015 by Kieren

Posted in Technology

End-to-end testing of modern web apps should involve running through key user journeys – including registration or signup. If this involves the user entering their email address, a “welcome” or “email address validation” email is typically involved. This can be tricky to test automatically, often using fixed test addresses and IMAP/POP3 client code.
Guerilla Mail is a free service which offers “disposable temporary e-mail addresses” on demand. Happily, there’s an API too – allowing the creation and checking of temporary mailboxes, programmatically.

We’ve built a Node.js wrapper around Guerilla Mail to facilitate its use. It’s installable with npm:

[code] npm install rr-guerillamail[/code]

It uses superagent as a HTTP client, and bluebird for promises. Here’s some sample code, demonstrating the creation of a random address, then a loop to wait for an email whose subject contains “xyzzy” before displaying the body content of that email:

[code]var mailbox = new TempMailbox();
.then(function(addr) { console.log(‘address: ‘ + addr); })
.then(function() {
return mailbox.waitForEmail(function(m) {
return (m.mail_subject.indexOf(‘xyzzy’) != -1);
.then(function(mail) {

The project is open source, MIT-licensed, and available here on GitHub. Please feel free to fork, contribute, or log any issues.