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 [email protected]
. The generated email will have the following headers
From: Example User <[email protected]>
We use username+token sub-addressing to provide a unique from
address.
To: [email protected]
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.
Dependencies
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. Then, authorize it within 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 byfetch.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 withdd 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.