Postmark Inbound Processing Demo (Rails)

This project contains a demo Rails app that shows how to implement inbound email processing using Postmark’s inbound webhooks.

The demo app replicates a simple blog. Readers can post responses to an article by sending an email to the app. Responses are processed by Postmark and forwarded to the Rails app using inbound webhooks. Once received the app associates a response with an article and saves it to the database.

You will need to have a Postmark account to run this demo. If you don’t have one already, sign up for a free account.

Getting Started

This tutorial assumes you have Ruby 2.4.1 installed. If not, please install it using RVM.

1. Clone this repository to your local machine.

git clone [email protected]:wildbit/inbound-demo-rails.git

2. Change into the inbound-demo-rails directory.

cd inbound-demo-rails

3. Install the project dependencies using bundler.

gem install bundler
bundle install

4. Create the SQLite database.

rails db:create

5. Run the database migrations.

rails db:migrate

6. Seed the database with some example articles.

rails db:seed

7. Open the /config/initializers/postmark.rb file and add the hash from the Postmark inbound address that emails will be sent to.

Rails.application.config.postmark_inbound_email_hash = 'YOUR_POSTMARK_INBOUND_EMAIL_ADDRESS_HASH'

You can find the inbound email address for a Postmark server on the server’s credentials page. The hash is the alphanumeric string that comes before the @ sign. (c0b622f2dkgj73be69c59033275ef521@inbound.postmarkapp.com)

8. Start Ultrahook. (See below for instructions on how to set up Ultrahook.)

ultrahook inbound-demo 3000

9. Navigate to your Postmark server’s inbound settings page (Settings → Inbound) and set the Webhook field to match your Ultrahook endpoint. (http://inbound-demo.YOUR_USER.ultrahook.com/responses)

10. Start the Rails server.

rails s

11. Navigate to http://0.0.0.0:3000/articles/1

12. Click the "Send a response" button at the bottom of the page to launch your email client.

13. Compose a simple message and hit send.

14. After a few seconds, refresh the page. You should see the content of your email appear in the Responses section at the bottom of the page.

If your message doesn’t appear, it’s likely there was an error in the Webhook handler. Open the console where you have ultrahook running and make sure there’s a log entry that shows the POST request to /responses returning a 200 status code.

Testing Inbound Webhooks Locally with Ultrahook

In order to test inbound webhooks while running the app locally, you can use a service called Ultrahook. Once set up, Ultrahook receives incoming webhooks from Postmark and forwards them to the instance of the app you have running locally on your machine.

The ultrahook ruby gem is included in this project’s Gemfile. Should you need to install it separately, run: gem install ultrahook.

1. Sign up for an account at ultrahook.com
2. Add your Ultrahook API key to a file in your home folder:

echo "api_key: YOUR_ULTRAHOOK_API_KEY" > ~/.ultrahook

3. Start Ultrahook, ensure the port supplied here matches the port your Rails app is running on (usually 3000).

ultrahook inbound-demo 3000

4. You should now see that Ultrahook has started running. The external URL you can use to forward requests to your local machine will be printed in your console.

Authenticated as YOUR_USER
Forwarding activated...
http://inbound-demo.YOUR_USER.ultrahook.com -> http://localhost:3000

5. Log in to your Postmark account.
6. Select a server that will handle your inbound emails and navigate to the inbound settings page (Settings → Inbound).
7. Set the webhook field using the Ultrahook URL that was output in your console and hit save. Don’t forget to add the /responses path to the end of the URL. This is the endpoint in the Rails app that will handle inbound emails.

http://inbound-demo.YOUR_USER.ultrahook.com/responses

Ultrahook will now forward any inbound webhooks from Postmark to your local machine.

Questions?

If you need help with anything in this demo, please create a ticket in the issue tracker.