Two Hacking Santas Present: Rails & The Inbound Parse Webhook

“Merry Haxmas!”–The first excited words I shouted on Wednesday morning as I remembered the day’s plans. I am a big kid. I love Christmas. I also love hacking. So why not combine the two?

The aim of the day was for Alex Reed (our latest SendGrid European Ambassador) and me to dress up like Santa, and live-stream ourselves creating “The 12 Hacks of Christmas.” Admittedly, we only managed 2 out of the 12 hacks, but we had a lot of fun, came up with some great ideas, and had over 300 viewers tune in to watch us. This was so much fun, we’re going to keep on hacking the holidays. (We’ll be back at Easter!)

One of the hacks we did manage to finish was the main Rails-based website, in which the public could email in bad Xmas cracker jokes, and general Xmas messages. Xmas crackers are cardboard tubes in wrapping paper that open with a pop. Inside are small trinkets and a strip of paper with a joke.

The hack I’ll describe below provides a way to share these bad jokes. We used SendGrid’s Inbound Parse Webhook to accept emails into our application.  Let’s take a look at how we used the Parse Webhook in our Rails app.

Prepare Rails for Jokes and Messages

The first thing we needed to do was generate a model in our app, to store the jokes and messages people send in. This model needed to differ between jokes and messages, and store the main content of the message. We generated a model in our Rails app to do just that:

rails g model Message message_type:string from:string body:text

Now we’ve done that, we need to do the same for the Controller. Once we’ve generated the controller, let’s open it up, and add some Xmas Message routing!  We want to be able to access a list of our received jokes/messages, and also want to be able to drill down into them, so lets create Index and Show actions:

Now, once we’ve set up displays for our jokes/messages, we need to actually set up a way of receiving them.  As mentioned, we’re going to do this by using SendGrid’s Inbound Parse Webhook, but also using ngrok to form a local tunnel to our Rails Server and SendGrid’s Web API.  Ngrok allows us to have SendGrid see our local application on a live domain, and therefore enables full use of the Webhooks API.

Prepare SendGrid’s Parse Webhook

To set up, head over to the Parse API docs, and read the “Setup” instructions.  This involves adding an MX record to your chosen domain to work as the hostname on which you want to accept emails.  Then we fill in our details on the Inbound Parse Settings page to use our new MX-added domain as the Hostname, and our ngrok tunnel as the URI.

Notice that in the above screenshot our URI has ‘/message’ on the end? Well, that’s because we’re going to set up Rails to accept an HTTP POST request on this URL. Let’s do that now.

Accept Incoming Email in Rails

Open up your messages_controller.rb file, and add in the following:

So, let’s break down the ‘/message’ route we just defined. We want to allow people to email in both jokes and other messages. For them to send a joke, we told them to include the word ‘Joke’ in the email Subject.  If they left the subject blank, or entered anything else, we would simply assume it was an Xmas message and store it accordingly.  To check the subject contents, we can simply use the attribute method in our receive action.  SendGrid’s Inbound Parse Webhook is very clever in this way, as we can check for any attribute the email contains.  We are not just limited to checking the subject or body, we can even check for attachments, check to see what type an attachment is, or even check from which device the attachment as added. For now, we just want to check the subject for the word ‘Joke,’ or otherwise.

Once we’ve checked the Subject, we are going to create a ‘Message’ (the model we defined earlier), and store the various attributes. As you can see, we are using an “if statement” to check if the subject contains ‘Joke,’ and if so, we are creating a Message with the type ‘joke’– otherwise, we are creating it with the type ‘xmas_message.’  We are storing the Message type, whomever sent the message, and the body of the joke/message.

Make note of the line that sends a response:

This is an important line. We must explicitly respond with a status code of 200, or SendGrid’s API will continue to try to send the email, until it is accepted. The message is unimportant for now, all we really need to note is the 200 status code.

Now then, once we’ve done that, we just need to add some routing to our routes.rb file, and we’ll be ready to accept incoming email. Go ahead and open up routes.rb and have it reflect the following:

Note in this routes file how we are telling Rails to accept a POST to ‘/message,’ and to use the Message action in our Messages Controller to handle said post.  Rails saves us a good amount of work here.  Because of its magic middleware, a JSON POST to ‘/message’ can arrive, and we simply tell it what to do from there. If you were to test this now (using Rails 4), you might encounter an error. Why? Well, because the POST request is coming from a separate entity, and Rails 4 Cross Site Scripting protection is going to kick in. For the sake of this demo, we’re simply going to tell it to skip on our Messages controller. At the top of your messages_controller.rb enter the following line:

Once this is in place, we should be able to test it out and receive an email.

Extend the Hack

SendGrid’s Inbound Parse Webhook is super easy to get setup with Rails. The possibilities are endless and the interactivity makes it one of the most fun APIs to work with.  In this Rails app, we could take it a step further and email each person back after they sent in a joke. We could simply collect their email address from the ‘From’ param and use ActionMailer to email them back saying “Thanks and Merry Christmas!” To get an idea of how to use Rails ActionMailer with SendGrid, take a look at the code example in our documentation.

So there you have it.  Getting set up with SendGrid’s Inbound Parse API on Rails is super simple, and lots of fun can be had. I assure you, Alex and me would have completed our 12 hacks of Christmas, had we not spent the entire day talking rubbish, messing round with the Live Feed, and later drinking beer. We did manage to have a hell of a lot of fun, and even got a technical article out of it! We will be back in the Easter, dressed up as Easter Bunnies, live streaming another day’s hacking!

A huge “thank you” to UStream for seeing us right for 8 hours, a massive “thanks” to the 300 viewers we had throughout the day, and a big “thanks” to all reading this article. I hope you all have a VERY Merry Christmas, and a fantastic New Year.

We left a present for you here.