diff options
Diffstat (limited to 'mail/docs/index.rst')
| -rw-r--r-- | mail/docs/index.rst | 66 |
1 files changed, 47 insertions, 19 deletions
diff --git a/mail/docs/index.rst b/mail/docs/index.rst index 8bacc51..a2133f4 100644 --- a/mail/docs/index.rst +++ b/mail/docs/index.rst @@ -3,21 +3,50 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to leap.mail's documentation! -===================================== +leap.mail +========= -This is the documentation for the ``leap.mail`` module. It is a twisted package -that exposes two services, ``smtp`` and ``imap``, that run local proxies and interact -with a remote ``LEAP`` provider that offers *a soledad syncronization endpoint* -and receive the outgoing email. +*decentralized and secure mail delivery and synchronization* + +This is the documentation for the ``leap.mail`` module. It is a `twisted`_ +package that allows to receive, process, send and access existing messages using +the `LEAP`_ platform. + +One way to use this library is to let it launch two standard mail services, +``smtp`` and ``imap``, that run as local proxies and interact with a remote +``LEAP`` provider that offers *a soledad syncronization endpoint* and receives +the outgoing email. This is what `Bitmask`_ client does. + +From the release 0.4.0 on, it's also possible to use a protocol-agnostic email +public API, so that third party mail clients can manipulate the data layer. This +is what the awesome MUA in the `Pixelated`_ project is using. + +.. _`twisted`: https://twistedmatrix.com/trac/ +.. _`LEAP`: https://leap.se/en/docs +.. _`Bitmask`: https://bitmask.net/en/features#email +.. _`Pixelated`: https://pixelated-project.org/ + +How does this all work? +----------------------- + +All the underlying data storage and sync is handled by a library called +`soledad`_, which handles encryption, storage and sync. Based on `u1db`_, +documents are stored locally as local ``sqlcipher`` tables, and syncs against +the soledad sync service in the provider. + +OpenPGP key generation and keyring management are handled by another leap +python library: `keymanager`_. See :ref:`the life cycle of a leap email <mail_journey>` for an overview of the life cycle of an email through ``LEAP`` providers. -``Soledad`` stores its documents as local ``sqlcipher`` tables, and syncs -against the soledad sync service in the provider. +.. _`Soledad`: https://leap.se/en/docs/design/soledad +.. _`u1db`: https://en.wikipedia.org/wiki/U1DB +.. _`keymanager`: https://github.com/leapcode/keymanager/ +Data model +---------- .. TODO clear document types documentation. The data model at the present moment consists of several *document types* that split email into @@ -25,13 +54,8 @@ different documents that are stored in ``Soledad``. The idea behind this is to keep clear the separation between *mutable* and *inmutable* parts, and still being able to reconstruct arbitrarily nested email structures easily. -In the coming releases we are going to be working towards the goal of exposing -a protocol-agnostic email public API, so that third party mail clients can -manipulate the data layer without having to resort to handling the sql tables or -doing direct u1db calls. The code will be transitioning towards a LEAPMail -public API that we can stabilize as soon as possible, and leaving the IMAP -server as another code entity that uses this lower layer. - +Documentation index +=================== .. .. Contents: @@ -48,14 +72,18 @@ API documentation ----------------- If you were looking for the documentation of the ``leap.mail`` module, you will -find it here. Beware that the public API will still be unstable for the next -development cycles. +find it here. + +Of special interest is the `public mail api`_, which should remain relatively +stable across the next few releases. + +.. _`public mail api`: api/mail.html#module-mail + .. toctree:: :maxdepth: 2 - api/mail - + api/leap.mail |