erebion/libervia-backend
Watch
1
0
Fork
You've already forked libervia-backend
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

doc (how-tos/email gateway): update the email gateway how-to:

Browse source 
pdate the gateway how-to to follow changes in configuration:
- configure the component with the simplifiedi configuration (`[component.email_gateway]`)
- remove the "supported features" section (redundant with email gateway documentation in
  `components.rst`)
This commit is contained in:
Goffi 2026-11-03 20:37:11 +01:00
commit b51b942103
2 changed files with 47 additions and 89 deletions
Download patch file Download diff file Expand all files Collapse all files

2
doc/howto_backup.rst
View file

@ -20,7 +20,7 @@ A backup is made of data *types*, included or excluded with ``-i/--include`` and
- ``private``: private storage: PEP-like client data, OMEMO crypto keys, PGP trust state - ``private``: private storage: PEP-like client data, OMEMO crypto keys, PGP trust state
- ``roster``: contact lists (from the roster cache in the database, kept up to date on - ``roster``: contact lists (from the roster cache in the database, kept up to date on
every connection) every connection)
- ``pep``: client PEP nodes and items (nick, avatar metadata, ...) - ``pep``: client PEP nodes and items (nick, avatar metadata, …)
- ``gpg``: GPG home per profile (public and secret keys) - ``gpg``: GPG home per profile (public and secret keys)
- ``files``: shared files (the blobs of ``~/.sat/files/``) - ``files``: shared files (the blobs of ``~/.sat/files/``)
- ``db``: full copy of the database (not portable, SQLite only) - ``db``: full copy of the database (not portable, SQLite only)

134
doc/howto_email_gateway.rst
View file

@ -4,18 +4,23 @@
How-To: Email Gateway How-To: Email Gateway
===================== =====================
This document explains how to configure and use the Libervia Email Gateway component. **Note that the Libervia backend must be installed first** (see :ref:`installation`). This document explains how to configure and use the Libervia Email Gateway component.
The Email Gateway component allows users to send and receive emails through XMPP clients and convert mailing list to XMPP forums. It connects to IMAP/SMTP servers using credentials provided by users during registration. The Email Gateway component allows users to send and receive emails through XMPP clients
and connect mailing lists to XMPP forums. It connects to IMAP/SMTP servers using
credentials provided by users during registration.
For the supported features and other details, refer to the :ref:`email-gateway` section
of the components documentation.
Prerequisites Prerequisites
------------- -------------
Before configuring the Email Gateway, ensure you have: Before configuring the Email Gateway, ensure you have:
1. Libervia backend installed and running (see :ref:`installation`) 1. Libervia backend installed and working (see :ref:`installation`)
2. An XMPP server configured with component support (such as Prosody, Ejabberd, Openfire, 2. An XMPP server configured with component support (such as Prosody, Ejabberd,
Tigase, MongooseIM, etc). Openfire, Tigase, MongooseIM, etc).
Configuration Steps Configuration Steps
------------------- -------------------
@ -30,7 +35,7 @@ Configuration Steps
-- Add to /etc/prosody/prosody.cfg.lua -- Add to /etc/prosody/prosody.cfg.lua
Component "email.example.org" Component "email.example.org"
component_secret = "your_unique_secret" component_secret = "secret"
*For Ejabberd:* *For Ejabberd:*
@ -46,30 +51,26 @@ Configuration Steps
module: ejabberd_service module: ejabberd_service
hosts: hosts:
"email.example.org": "email.example.org":
password: "your_unique_secret" password: "secret"
**Important:** Replace `email.example.org` with your actual domain and `your_unique_secret` with a secure random string (you may use `openssl rand -hex 16` to generate). Of course replace ``email.example.org`` with your actual domain and ``secret`` with a
secure random string (you may use ``openssl rand -hex 16`` to generate one).
2. **Create Libervia Profile for Email Gateway** 2. **Configure the Email Gateway Component in Libervia**
Use the Libervia CLI to create the gateway profile: Add the following section to your Libervia configuration file (usually
``libervia.toml``), using the same JID and shared secret as the ones configured on
your XMPP server:
.. code-block:: bash .. code-block:: toml
$ li profile create email-gateway \ [component.email_gateway]
-j email.example.org \ jid = "email.example.org"
-p "" \ secret = "secret"
-x "your_unique_secret" \
-C email-gateway \
-A
This creates a profile named `email-gateway` with: The component profile is then created automatically on backend startup, and the
component starts automatically. See :ref:`components` for details about the
- JID: `email.example.org` components configuration.
- No profile password (`-p ""`), to avoid password prompts during Libervia backend startup.
- XMPP server shared secret (`-x "your_unique_secret"`)
- Component entry point (`-C email-gateway`)
- Auto-connect enabled (`-A`)
3. **User Registration** 3. **User Registration**
@ -81,7 +82,7 @@ Configuration Steps
.. code-block:: bash .. code-block:: bash
$ li gateway register -cp your_user_profile email.example.org $ li gateway register -c -p your_user_profile email.example.org
**Registration Fields** **Registration Fields**
@ -117,55 +118,16 @@ Configuration Steps
SMTP Password SMTP Password
Password for SMTP authentication Password for SMTP authentication
**Important Notes** .. note::
- Ensure your IMAP/SMTP servers are accessible from the Libervia backend - Ensure your IMAP/SMTP servers are accessible from the Libervia backend
- The IMAP server must support the IDLE extension for real-time notifications - The IMAP server must support the IDLE extension for real-time notifications
Configuration Configuration
------------- -------------
The Email Gateway uses user-specific registration data - **no additional configuration is needed** in Libervia's main config file. All settings are stored per-user during registration. Besides the component configuration described above, no other configuration is needed:
the gateway uses user-specific data provided during registration.
Supported Features
------------------
- **Normal Email Conversion**: Standard email messages are converted to XMPP chat
messages. Each email appears as a regular message in the user's XMPP client.
- **Mailing List Handling**: Mailing list emails are converted to PubSub blog nodes
(microblogging) using XEP-0277:
* Each mailing list becomes a separate pubsub node
* Each email in the list becomes a blog item
* Replies to specific topics appear as comments to the corresponding item
* Title tags within square brackets (e.g., `[tag]`) are converted to blog categories
* Only the recipient JID associated with the mailing list can access the pubsub node by
default.
- **Extended Addressing Support**: Properly handles email addressing metadata (To, CC,
BCC) via XEP‑0033, converting it into XMPP addressing information for correct delivery.
This allows multi‑party discussions without relying on group chat (XEP‑0045 MUC), which
can be tricky to implement in email‑based communication.
- **Header Conversion**: Converts important email headers to XMPP metadata, such as:
* Keywords → XMPP "Keywords" header (XEP-0131)
* Importance → XMPP "Urgency" header (XEP-0131)
- **Message Cleaning**: Automatically detects noisy elements in mailing list emails
(quoted replies, signatures) and tags them with a CSS class named "noise" so XMPP
clients can selectively hide or visually distinguish these parts of the message.
- **Attachment Management**: Allows users to retrieve and delete email attachments via
PubSub File Sharing (XEP-0498).
.. note::
Attachments cannot yet be sent with messages (this
functionality is in development).
- **End-to-End Encryption**: Supports Gateway Relayed Encryption (not yet an official XEP)
for encrypted email messages. Requires XMPP clients that implement this specification.
Troubleshooting Troubleshooting
--------------- ---------------
@ -178,37 +140,33 @@ Troubleshooting
- Solution - Solution
* - XMPP component connection failed * - XMPP component connection failed
- Verify the shared secret matches on **both** Libervia and the XMPP server. - Verify the shared secret matches on **both** Libervia and the XMPP server.
The component JID must *exactly* match the JID configured on the XMPP server (e.g. The component JID must *exactly* match the JID configured on the XMPP server
“email.example.org” in Prosody must match the JID you set when creating the (e.g. "email.example.org" in Prosody must match the JID you set in the Libervia
Libervia profile). configuration).
* - User registration fails * - User registration fails
- * Check the IMAP/SMTP credentials and make sure the servers are reachable from the - * Check the IMAP credentials and make sure the IMAP server is reachable from the
Libervia host. Libervia host.
* Verify that the IMAP server supports the **IDLE** extension (required for * Verify that the IMAP server supports the **IDLE** extension (required for
real‑time notifications). real-time notifications).
* If you use self‑signed certificates, add them to the system trust store. * If you use self-signed certificates, add them to the system trust store.
* - Email not received * - Email not received
- * Confirm the user’s email credentials (you can re-register to check). - * Confirm the user's email credentials (you can re-register to check).
* Check Libervia Backend logs to ensure that the IMAP connection succeeded. * Check Libervia Backend logs to ensure that the IMAP connection succeeded.
* Verify that messages are arriving in the user’s INBOX. * Verify that messages are arriving in the user's INBOX.
* - “DBus not launched” error * - Email not sent
- Follow :ref:`installation_dbus` instructions for headless servers – the - * Check the SMTP credentials and make sure the SMTP server is reachable from the
Libervia backend relies on D‑Bus to run. Libervia host.
* Check the Libervia backend logs for the sending error.
* - Attachments not appearing * - Attachments not appearing
- The Email Gateway can *retrieve* attachments, but does not yet deliver them with - The Email Gateway can *retrieve* attachments, but does not yet deliver them with
outgoing messages (feature work in progress). outgoing messages (feature work in progress).
* - Encrypted emails not working * - Encrypted emails not working
- “Gateway Relayed Encryption” is a work‑in‑progress extension (not yet an official XEP). - "Gateway Relayed Encryption" is a work-in-progress extension (not yet an official
Use a client that implements this specification. XEP). Use a client that implements this specification.
* - Mailing lists not converted * - Mailing lists not converted
- Verify that the incoming e‑mail contains a **valid “List‑ID”** header. The value - Verify that the incoming e-mail contains a **valid "List-ID"** header. The value
must match the format expected for PubSub node creation. must match the format expected for PubSub node creation.
.. note:: .. note::
The Email Gateway is under active development. Some features may have limitations. The Email Gateway is under active development. Some features may have limitations.
See Also
--------
- For Libervia components overview: :ref:`components`