# HG changeset patch
# User Goffi <goffi@goffi.org>
# Date 1725638864 -7200
# Node ID 92a886f31581af9a08022bc87e79a9a421a88c98
# Parent  a7ec325246fbb59dcda22d1aebaa1913b08b4d64
doc (components): new Email gateway documentation:

fix 449

diff -r a7ec325246fb -r 92a886f31581 doc/components.rst
--- a/doc/components.rst	Fri Sep 06 18:07:17 2024 +0200
+++ b/doc/components.rst	Fri Sep 06 18:07:44 2024 +0200
@@ -892,10 +892,6 @@
 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 @@
   **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
+