Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Mailchain Specification


Mailchain enables blockchain-based email-like messaging with plain or rich text and attachment capabilities. Using blockchain protocols and decentralized storage, Mailchain delivers a simple, secure, messaging experience.

Account holders or owners of a public address often need to communicate in the context of the account or public address. Communication may relate to transactions, account actions or some type of notification.

Examples of use cases for blockchain messaging include invoicing, receipts, contacting users of a service or application developers.

The majority of blockchain protocols provide no standard way to handle messaging. Some account holders have sent messages as an encrypted or unencrypted string included in transaction data. Some applications work around the problem by asking users to link another method of contact (e.g. email address, phone number etc.) to an application. This compromises anonymity by asking users to link or reveal an identity. It also increases exposure to security risks, and relies on additional centralized services.

This proposal outlines how Mailchain gives users the ability to send and receive rich-media HTML messages between public addresses through a simple, email-like interface. All message contents and attachments are encrypted so only the intended recipient of the message can decrypt and view messages.

Mailchain Message Lifecycle

Mailchain is a simple, secure and practical standard which can be implemented across different blockchains. It uses underlying native blockchain protocol capabilities including addressing, immutability, data transmission, and cryptography.

The basic message flow is as follows:

  • A user sends a message. The message is encrypted and stored using the recipient’s public key so that only the recipient can locate and decrypt the message contents. The encrypted location of the message is sent by the sender to the recipient in the data field of a transaction.

  • To read a message, a recipient uses a corresponding private key to decrypt the location of the message from the data field of a transaction and decrypt the message contents.

Anonymity, Privacy and Encryption

Mailchain considers anonymity of senders and recipients a high priority.

The Mailchain application handles encryption and decryption of data (see Mailchain Message Lifecycle for further details). All data is encrypted when transmitted or stored outside of the mailchain/mailchain-web application flow.

Anyone with the recipient account’s private key can decrypt messages, so it is important to secure private keys.

The underlying blockchain protocol (e.g. ethereum, bitcoin etc.) is responsible for dictating the sender & recipient privacy model.

What's here?

There are four important files in this repository:

  1. mailchain_specification - This lays out the specification for mailchain.

  2. mailchain_tenets - This declares the approach to design and decision-making.

  3. mailchain_use_cases - This outlines some potential use cases for mailchain (feel free to suggest more).

  4. mailchain_threat_model - This details known threats and how they might be mitigated.

Working in this repo

We ❤️ pull requests! See for info on contributing changes.


Mailchain implements Semantic Versioning (see for more information).

From version 1.0.0:

  • New versions should be backwards compatible
  • Software must be capable of reading old versions


By contributing to the Mailchain Specification repository, you agree that your contributions will be licensed under its Apache 2.0 License.


The specification and requirements for Mailchain





No releases published


No packages published