Postman

Postman is a simple IMAP idling daemon which will monitor the specified mailbox for incoming email messages and delivery them to a postback endpoint.

It works incredibly well for applications which need to process incoming email messages as they arrive. ie: helpdesk apps.

Installation

Postman is written in Go. This means it should run under Windows, Linux, FreeBSD and OSX.

Binary

Installation is very easy. Simply download the appropiate version for your platform from the releases page. Once downloaded it can be run from anywhere. You don't need to install it into a global location. This works well for shared hosts and other systems where you may not have a privileged account.

If you want to install it globally, I'd recommend somewherewhich already is in your user's path. For example: /usr/local/bin may be a good candidate.

The Postman executable has no external dependencies

Building from source

As with any go package building from source is pretty easy. First:

go get github.com/etrepat/postman

Then build:

cd /path/to/postman
go build -o postman main.go

Now you should have a postman binary available in the project folder. It's already ready to run!

Usage

Postman is a rather simple tool. The first thing you should do is run postman -h and see the available parameters. You'll immediately see that the options are pretty self explanatory and basically involve 3 areas: connection options (host, port, user, ...), mailbox selection (which IMAP mailbox to monitor) and operation mode.

postman -h imap.gmail.com --ssl -U <username> -P <password> --postback-url=<receiving host>

Connection management parameters

-h, --host

Specify the hostname or ip address of IMAP server.

-p, --port

IMAP server port number. It will default 143 or 993 if ssl is enforced.

--ssl

Enforce a SSL connection. Will default to true if port is set to 993.

-U, --user

The IMAP server login username.

-P, --password

The IMAP server login password.

Mailbox selection and mode of operation parameters

-b, --mailbox

The IMAP mailbox name to start monitoring on. Will default to INBOX if not given.

-m, --mode

Sets the daemon mode of operation. Must be one of: logger, postback.

The logger mode is mainly for debugging/testing purposes and it will "spit out" the raw email message data into stdout whenever a new mail arrives at the specified IMAP mailbox.

In postback mode, Postman will grab the raw email message data and perform a POST request to an endpoint of your choosing. This mode allows for the following additional parameters:

• --postback-url: URL to POST incoming raw email message data. By default all data will be sent in the post body with a text/plain content-type.
• --encode: Will perform the POST request as if it were form data (x-form-urlencoded) wrapping the raw email message in a post parameter.
• --parname: Sets the parameter name to be used when --encode is set. Defaults to message.

Receiving email data in Rails

This utility was developed as part of a Rails application. You should take into consideration the following points when using the postback functionality in a Rails app:

• First, you should disable forgery protection on the receiving controller action.
• If you need to use an authentication token, you may add it to the postback-url as a query parameter. You may use ENV vars for that.
• Doing something like raw_email = request.body.read in the controller will get you the raw email message data as a string. You can then use the awesome mail gem like this: mail = Mail.new(raw_email) to parse the email message and retrieve all the information you need.

Using with Upstart

To avoid service interruptions, I'd recommend using Postman in combination with some process monitoring tool. For most of my use cases though I personally find that Upstart is just enough. Here's an sample init script for Postman which may be used as an starting point:

start on runlevel [2345]
stop on runlevel [016]

respawn
respawn limit 10 90

exec su - <user> -c 'cd /home/<user>/sites/<my-awesome-app>; ./bin/postman -h imap.gmail.com --ssl -U $SMTP_USERNAME -P $SMTP_PASSWD -m postback --postback-url=$POSTMAN_DELIVERY_URL >> /var/log/<my-awesome-app>/postman.log 2>&1'

Contributing

Thinking of contributing? Maybe you've found some nasty bug? That's great news!

1. Fork & clone the project: git clone git@github.com:your-username/postman.git.
2. Create your bugfix/feature branch and code away your changes. (git checkout -b my-new-feature).
3. Push to your fork.
4. Submit new a pull request.

License

Postman is licensed under the terms of the MIT License (See LICENSE file for details).

---

Coded by Estanislau Trepat (etrepat). I'm also @etrepat on twitter.