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.

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

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

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!

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>

Specify the hostname or ip address of IMAP server.

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

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

The IMAP server login username.

The IMAP server login password.

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

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

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. smart gives just info about the email in the logs. hipchat will send the message to a hipchat room, need to specify room name and room authentication.

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.

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.

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'

##Docker:

###From Scratch, resulting image aprox 8.9 megs

#####To cross compile (build on Mac for Docker Container)

http://stackoverflow.com/questions/27412601/cross-compiling-go

#####Cert file generated by following

http://slowhash.com/2013/08/17/ca-certificates-crt-for-macosx/

#####Go build command

CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o main .

https://blog.codeship.com/building-minimal-docker-containers-for-go-applications/

#####Docker build command

docker build -t jcastillo/postman:v1 -f Dockerfile.scratch .

#####Image based off this repo

https://registry.hub.docker.com/u/jcastillo/postman/

#####Example calling docker

The command line parameters can be specified via environment variables, Mode is defaulted to 'hipchat' if not specified in environment variable. SSL to true. Host to imap.gmail.com.

docker run -e POSTMAN_EMAIL=[email@gmail.com] -e POSTMAN_PASSWORD=[email_password] -e POSTMAN_ROOMAUTH=[hipchat_room_auth] -e POSTMAN_ROOMNAME=[hipchat_room_name] -d jcastillo/postman:v2

Brackets above were just added to show these were examples, they shouldn't be included in actual call

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.

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.