heroku dev center
Mail2Webhook

This add-on is operated by Devels Advocates LLP

Receive incoming email as HTTP POST to your web app

Mail2Webhook

Last Updated: 07 April 2014

The Mail2Webhook add-on is currently in beta.

Table of Contents

Mail2Webhook is an add-on for receiving emails in your web app easily and efficiently.

No more hacky setup of using Gmail inbox, polling every minute for new emails, and suffering from delays. Your webhook is called immediately for each email that arrives.

Provisioning the add-on

Mail2Webhook can be attached to a Heroku application via the CLI:

$ heroku addons:add mail2webhook
-----> Adding mail2webhook to sharp-mountain-4005... done, v18 (free)

Once Mail2Webhook has been added a MAIL2WEBHOOK_EMAIL setting will be available in the app configuration, which you can use as your Reply-To for all the emails you send out. This can be confirmed using the heroku config:get command.

$ heroku config:get MAIL2WEBHOOK_EMAIL
abcdef@mail2webhook.com

Configure the add-on

Once you’ve added the add-on, you’ll need to configure the webhook URL. Do this through the configuration panel on Dashboard. You can access this in two ways. You can use the CLI:

$ heroku addons:open mail2webhook

Or you can click through from your app dashboard, into the Mail2Webhook add-on, and set the webhook URL you want for receiving the emails.

Your application is now configured to fully integrate with the add-on.

Sample code

Incoming emails can be handled by processing a HTTP POST for a application/x-www-form-urlencoded request; the entire email is available in the message parameter.

For your convenience, if you’re using Ruby on Rails or Node.js, we have some ready to use code for you to copy and paste

Ruby on Rails

Create your controller file app/controllers/incoming_emails_controller.rb and paste the following code inside

require 'mail'

class IncomingEmailsController < ApplicationController
  skip_before_filter :verify_authenticity_token, only: :create
  def create
    mail = Mail.new(params[:message])

    # API for https://github.com/mikel/mail
    mail.from    # => ["sender@example.com"]
    mail.to      # => ["example@mail2webhook.com"]
    mail.subject # => "Testing 1 2 3"
    mail.parts   # => [#<Mail::Part:70135193504060, Multipart: false, Headers: <Content-Type: text/plain; charset=ISO-8859-1>>,...]
    mail.body    # => #<Mail::Body:...>

    render text: "OK"
  end
end

Add the following line of code into your config/routes.rb

post 'incoming_emails' => 'incoming_emails#create'

Use this route in as the webhook URL. For example, in this case it may be something like http://your.app.com/incoming_emails.

Node.js

Install the mailparser npm package

$ npm install mailparser

And execute the following Node.js script

var http = require('http');
var querystring = require('querystring');
var MailParser = require("mailparser").MailParser; // https://github.com/andris9/mailparser

var server = http.createServer();
server.addListener('request', function(req, res) {
  var chunks = [];
  req.on('data', chunks.push.bind(chunks));
  req.on('end', function() {
    var mailparser = new MailParser();
    mailparser.on("end", function(mail_object) {

      // API for https://github.com/andris9/mailparser
      mail_object.from; // [ { address: 'sender@example.com', name: 'Sender Name' } ]
      mail_object.to;   // [ { address: 'example@mail2webhook.com', name: '' } ]
      mail_object.subject; // "Testing 1 2 3"
      mail_object.html;
      mail_object.text;
      console.log(mail_object.from, mail_object.to, mail_object.subject);
      console.log(mail_object);

      res.writeHead(200, {'content-type': 'text/plain'});
      res.end();
    });
    var params = querystring.parse(chunks.join("").toString());
    mailparser.write(params['message']);
    mailparser.end();
  });
});
var port = process.env.PORT || 3000;
console.log(' [*] Listening on 0.0.0.0:' + port);
server.listen(port, '0.0.0.0');

Removing the add-on

Mail2Webhook can be removed via the CLI.

This will destroy all associated data and cannot be undone!

$ heroku addons:remove mail2webhook
-----> Removing mail2webhook from sharp-mountain-4005... done, v20 (free)

Support

All Mail2Webhook support and runtime issues should be submitted to Mail2Webhook Support