Burnside

Panic's Burnside bridges Twitter to email and back.

It's particularly useful for companies that provide Twitter support. By handling @questions through an e-mail client, support agents can reply to tweets much quicker, answered tweets can be tracked by "Archiving" them or moving them to a subfolder, multiple agents can work out of the same mailbox (via IMAP), and an easily-searchable archive of tweets can be built over time.

Burnside is intended for shell-level/e-mail server administrators, and requires:

Procmail (already working with user accounts on an IMAP/SMTP server)
Cron
Ruby
SMTP server that supports "+" character recipient delimiter for sub-addressing

Other configurations may be possible based on your expertise.

How it works

Receiving

Periodically, the fetch.rb script is run and it generates an email for every new @mention. We'll assume you're fetching from a twitter account called PanicGWTest and sending mail to twitter@panicburnside.org. The generated email will have the following headers

From: Example User <twitter+ohhaiexample@panicburnside.org>

We use username+token sub-addressing to provide a unique from address.

To: twitter@panicburnside.org
Message-ID: <1234567890@twitter-super_secret_auth_token.panicburnside.org>

The Message-ID contains the tweet status ID as well as the auth_token.

Subject: Tweet from Example User (@ohhaiexample)
X-Burnside: ignore

The X-Burnside: ignore header prevents our procmail recipe from processing these emails as they come in. This is necessary in the case where your from and to mailboxes are the same.

Sending

When a reply to a tweet is received by procmail it's parsed by tweet.rb and a new tweet is generated. If the new tweet is over 140 characters then the email is bounced. If the In-Reply-To header doesn't contain the auth_token then the message is bounced.

The format of the new tweet is

#{@to} #{@reply_text} #{@sig}

sig is a space followed by an em-dash followed by the first letter of the sender's name in the From: header of the reply. Currently tweet.rb splits the reply text using the regex /(.*)On.*wrote:.*/m so this will obviously be a problem for non-English users.

Dependancies

sudo gem install bundler
git clone https://github.com/panicinc/burnside
cd burnside
bundle install --deployment

Twitter Application

Create a new Twitter Application and get its consumer key and secret as well as authorize your account to make use of it.

Configuration

Copy the .sample files and rename them. For these instructions we'll assume you make a configuration set named "PanicGWTest". You should end up with the following files:

PanicGWTest.header.erb
PanicGWTest.html.erb
PanicGWTest.txt.erb
PanicGWTest.yml

Fill in the details of the .yml file with the OAuth information you got when you created and authorized your application.

The mail.delivery sections contains basic IMAP authentication details.
to: should be the email address that will receive the messages generated by fetch.rb.
mailbox is the mail account/alias that messages will be "from". An agent's reply will be sent here.
The auth_token field should contain a randomly generated string of any length. An easy way to make one on Mac OS is with

dd if=/dev/urandom count=4 2>/dev/null | openssl dgst -sha1

Usage

To bridge your tweets to email you'll run bin/fetch.rb as follows

./bin/fetch.rb -c config/PanicGWTest.yml

This task could be run via cron like

*/5 * * * * cd $HOME/burnside; ./bin/fetch.rb -c config/PanicGWTest.yml

To handle incoming email you'll need to setup Procmail. There's a sample recipe in the config folder. Alternatively, you could write a script that accesses your IMAP inbox and then pipe messages through tweet.rb. Frankly, if you don't already have Procmail setup then this might be a less painful approach.

Caveats

Burnside was written to be used with Apple Mail so there are a few assumptions about how it formats emails.

Contributing

Feel free to fork and send us pull requests

Bug Reporting

Burnside is an unsupported, unofficial Panic product. But, if you can't contribute directly, please file bugs at https://hive.panic.com in the Burnside project. You have to register first, via the Register link in the upper-right hand corner.

Extras

See Burnside Mail Plugin, our plugin for Apple Mail that adds a character count to ensure that your Tweets aren't too long.

dreww/burnside