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
Building from source
As with any go package building from source is pretty easy. First:
go get github.com/etrepat/postman
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>
Connection management parameters
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.
Mailbox selection and mode of operation parameters
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 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.
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
--encodeis 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-urlas a query parameter. You may use ENV vars for that.
- Doing something like
raw_email = request.body.readin 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  stop on runlevel  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'
Thinking of contributing? Maybe you’ve found some nasty bug? That’s great news!
- Fork & clone the project:
git clone firstname.lastname@example.org:your-username/postman.git.
- Create your bugfix/feature branch and code away your changes. (git checkout -b my-new-feature).
- Push to your fork.
- Submit new a pull request.
Postman is licensed under the terms of the MIT License (See LICENSE file for details).