doc (components): new Email gateway documentation:

fix 449

doc/components.rst

@@ -892,10 +892,6 @@ The component currently integrates the `Galène project`_, as it is a complete,
 easy to install service. Other projects may be integrated in the future if the need
 arises.
 
-.. note::
-
-  This component is **work in progress** and under heavy development.
-
 Please ensure that Galène is already installed on your device.
 
 If the ``galene`` executable is not in your ``PATH`` environment variable, you can specify its
@@ -920,3 +916,36 @@ All options are to be set in the ``[component conferences]`` section.
   **default**: 9443
 
 .. _Galène project: https://galene.org/
+
+
+Email Gateway
+-------------
+
+**entry_point:** ``email-gateway``
+
+.. note::
+
+  This component is **work in progress** and under heavy development.
+
+This gateway links the email network and XMPP in both directions. It allows sending and
+receiving emails using XMPP clients.
+
+The gateway uses an existing email account configured using IMAP4 and SMTP. IMAP4 is used
+for reception and the server must support IMAP4 rev1 protocol with the "IDLE" extension
+for real-time notifications. SMTP is used for sending emails.
+
+To use the gateway, one must register through `XEP-0100 (Gateway Interaction)`_. Once
+registered, connection to the IMAP server is started immediately, and new emails in the
+``INBOX`` mailbox are received as XMPP messages.
+
+For the moment, mailboxes are used in read-only mode, meaning that the read status and
+other attributes are not changed, and messages will appear normally in other MUA (email
+clients).
+
+To send a message, just write to the corresponding JID. Email addresses are mapped to JIDs
+using `XEP-0106 (JID Escaping)`_: the email is escaped and used as the user-part of the
+gateway JID.
+
+.. _XEP-0100 (Gateway Interaction): https://xmpp.org/extensions/xep-0100.html
+.. _XEP-0106 (JID Escaping): https://xmpp.org/extensions/xep-0106.html
+