Today I will be talking about the baal project, and what it entails.

The baal project can be found here, if you would like to contribute, please feel free to drop me an email containing your patch.

Now, you migh be asking yourself: "what exactly is baal", allow me to answer your question. baal (always written lowercase) was originally meant to be an implementation of my good friend Tristan (deavmi) Kildaire's json based email protocol butterfly, but then slowly morphed into my own take on a json based email protocol, and hence all credit for the idea should be directed towards deavmi.


Everything in baal is json based, config files, emails, etc. This keeps it simple and allows for easily extending config format without breaking anything else. i.e we keep backwords compatibility.

Likewise, persistant storage is also done as json files (Although I am tempted to use a database, if I do, I will use sqlite3, as baal is not inteded to have a large concurrent user base (max something like 32 users), as it is inteded to be used almost on a user by user basis, that is each user hosts thier own server.

baal query

First, everything that happens in baal is in the form of a baal query, for example.

  • Sending an email
  • Syncing mailboxes
  • Creating mailboxes

A baal query is a json messaged, prefixed with a VLI of 4 bytes, with the json being of the form:

	"query" : "BAAL_QUERY",
	"data"  : <Any json object>

We have 2 fields to unpack, namely

  • query
    • What type of query this is, for example: register.
  • data
    • The data needed to fulfill this query, varies from query to query.

More Queries

Since the documentation for baal is rather lacking, this blog post acts as the first offical documentation for baal, in the next post (Which will most likely be written tomorrow), I shall explain more of the currently implemented queries

Slightly long, tl;dr on baal

  • single binary (for both server and client).
    • That is, to run a server or client for the baal protocol, you just use a single (more specifically, the same) binary.
    • This is vastly simpler to setting up an email server, and should allow users to easily setup thier own baal mail servers.
  • open protocol (well it still needs to be written).
  • Multi user registration
  • Rich command set
    • Easily extensible, adding new commands consists of simply creating a starter function, which takes argc and argv (as a usual C prog does), and execs the command.
  • Thread safe
    • A baal server can handle up to n (Decided at compile time) concurrent connections, and all operations within these threads are (as of writing this) thread safe.
  • Server query hooks
    • The server can easily be extended, as the handling of incoming requests consists of passing the incoming packet to the approriate hook, hence adding new features requires 2 simple changes:
      • Adding a function which execs the hook
      • Adding a mapping of the command string in the request json to the hook function
    • Examples of hooks getting exec'd can be found here.

Actual tl;dr

baal = json + sockets = email server and or client

~ Skiqqy