From Organic Design wiki
Legacy.svg Legacy: This article describes a concept that has been superseded in the course of ongoing development on the Organic Design wiki. Please do not develop this any further or base work on this concept, this is only useful for a historic record of work done. You may find a link to the currently used concept or function in this article, if not you can contact the author to find out what has taken the place of this legacy item.

Bitmessage is a peer-to-peer communications protocol based on the Bitcoin crypto-currency used to send encrypted messages to another person or to many subscribers. It is decentralized and trustless, meaning that you need-not inherently trust any entities like root certificate authorities. It uses strong authentication which means that the sender of a message cannot be spoofed, and it aims to hide "non-content" data, like the sender and receiver of messages, from passive eavesdroppers like those running warrantless wiretapping programs. If Bitmessage is completely new to you, you may wish to start by reading Setting up and using Bitmessage by CryptoJunky, or you could go straight to the whitepaper.


Installation is very simple on modern GNU/Linux based operating systems. You may need to install python-qt4 first, then simply git clone it as shown here. And create a desktop launcher for it as shown in our GNOME article.

Using Bitmessage from the command line

For use on servers or for testing local applications that use the Bitmessage via its API you can install the PyBitmessage-Daemon which can just be unpacked into the same location as PyBitmessage. When the PyBitmessage-Daemon/ script is run it will connect to the local Bitmessage service using the API use and password found in the key.dat file of the Bitmessage's configuration. Note that the key file is found by checking the home directory's .config/PyBitmessage location so if you run Bitmessage under an unprivileged user you'll need to use the sudo command to run the script first. Also for some reason they've used "python-2.7.x" in the shebang statement at the start of the script so you can't run the script directly, you need to call it via python2.7. For example if we're running as the unprivileged user bmuser we would run it as follows:

sudo -u bmuser python2.7 /home/bmuser/PyBitmessage-Daemon/

You can then type the command apiTest to see if the connection to the local Bitmessage is working properly, and if so, do help to see a list of available commands you can issue.

Use your mail client as the UI with bmwrapper

Brilliant little script that sets up a basic POP3 and SMTP server on localhost to give Bitmessage an email interface for example that Thunderbird can connect to. This means the messages can be organised in a local folder structure or easily coped to your IMAP structure.

  • First enable the Bitmessage API in your local keys.dat configuration file.
  • Install the PyBitmessage-Daemon script into your home folder (I used git clone for easy update) and run it with python
  • Install the bmwrapper into your home (I used git clone again)
  • Set up an account on your mail client to localhost, POP3 on 12344 and SMTP on 12345 as shown here.
  • Create a .desktop file that runs a launcher shell script
  • Create your launcher script that runs another separate launch script for each of the three e.g.
cd ~/PyBitmessage
./ & ./ & ./
  • Create each of the three launchers one to run each of the scripts with python2.7, for example the first of mine is:
python2.7 ~/PyBitmessage/src/
  • Ensure all the launchers have executable permission. This complicated procedure is required because each one is a daemon that doesn't return and won't run in the background using the ampersand.
  • You can check if they're running with netstat -nlp and check you have apps listening on 8442, 12344 and 12345, e.g.
tcp   0   0*   LISTEN   3575/python2.7  
tcp   0   0*   LISTEN   3575/python2.7  
tcp   0   0*   LISTEN   3577/python2.7  
tcp   0   0*   LISTEN   3577/python2.7

Bitmessage + Open Transactions

A very interesting thread started in BitcoinTalk here about joining Bitmessage with Open Transactions to produce a completely p2p anonymous transaction system far superior to Bitcoin or Ripple in terms of security, anonymity and the power of financial instruments it provides. See more on the Open Transactions article.

Bitmessage gateway

I've been finding Bitmessage difficult to run especially as our net connection can be very low bandwidth, so often I won't run it for days at a time and then miss out on messages. When I do run it I have to wait a long time before messages will arrive. So I've decided to run it on the server as a daemon (using these settings to start it automatically as a service), and then integrate it with Exim so that I can receive the messages in my usual inbox. This is quite secure because both sending and receiving is done over encrypted channel to our own server.

I've made a couple of Python scripts, bm-gateway/ and bm-gateway/ which utilise the functionality of bmwrapper on hosts that already have a running mail server and acts as a gateway between the local Bitmessage instance and the mail server without starting up an additional SMTP and POP server.

Incoming Bitmessage messages are now sent to a local email address, actually any email address would do, but if it's not local, then the security of using Bitmessage would be compromised. The email address that correspond to each Bitmessage address in the "addresses" section of the gateway configuration file in the form foo@bar.baz = BM-xxxxxxx. If an incoming Bitmessage's address does not match any of the email addresses then the first is used as a "catch all".

Outgoing messages are sent to a local user account that is configured to forward the messages to Bitmessage. The email address of this account is defined in the "settings" section of the configuration. For example using Exim a filter can be set up in the local user's .forward file that uses the pipe command to send the message to this script for forwarding to Bitmessage. This user account is also the user under which Bitmessage should be running, and all them (PyBitmessage, PyBitmessage-Daemon, bmwrapper and bm-gateway) should be located in this account's home directory.


First set up an unprivileged user account to run Bitmessage and all the scripts under. Install Bitmessage, Bitmessage-Daemon, bmwrapper and bm-gateway into this user's home directory. Ensure that daemon and API are enabled in your .config/PyBitmessage/keys.dat configuration file for Bitmessage. Set up a .config file in the bm-gateway directory containing a "settings" and a "addresses" section. The first section contains a "gateway" value with the email address of the user running the scripts, and the second section contains mappings of each of your email addresses to Bitmessage addresses, including the address of the account through which all outgoing messages will be sent, e.g.

gateway =

[addresses] = BM-2D8WUhjPbRABrRdZqQeYZUAJdpvxDfjej4 = BM-2D7F9ILxyeVXqrMsfyRcPZuhzhDXjMtkbQ

Set up an email account for this gateway user which will be the generic account through which all outgoing Bitmessage messages will sent, in the example configuration above, this email address is assumed to be "". You'll need to set up a way for the emails to be sent to the bm-gateway/ script instead of to standard delivery. For Exim this can be done by using a filter in a .forward file in the user's home directory that uses the pipe command. Here's an example filter which uses a condition to check that it's a Bitmessage recipient incase the user also has normal mail delivered too.

# Exim filter
   $header_to matches "^BM-"
   pipe "$home/bm-gateway/"

The bm-gateway/ script will need to be called on a regular basis to check for new incoming Bitmessage messages and forward them to the appropriate local email account. You can add something similar to the following to your crontab to achieve this:

*/5 * * * * bitmessage /home/bitmessage/bm-gateway/ > /dev/null


Nothing needs to be done to receive or reply to messages, they just arrive in the inbox and can be replied to in to in the normal way. Sending messages to Bitmessage addresses that isn't a reply is done by using the following format for the To field:

BM-2D7F9ILxyeABCD1234xyzfPZuhzhD <bitmessage&#64;>

where the name portion is the recipient Bitmessage address, and the email address portion is the address of the account that was set up to receive all the messages for the gateway to forward to Bitmessage - in our example above,

Note that users on the same gateway cannot sent messages to each other via the Bitmessage network, because Bitmessage doesn't allow a user to send to one of their own addresses, and in the case of the gateway, all the local user's addresses are on the same Bitmessage instance. If this is attempted, the script will raise an exception, and in the case of Exim the message and the exception details will be returned to the sender.

See also