doc: Add How-To for Email Gateway:
This How-To complete installation instruction with an easy-to follow document to completely install the Email <=> XMPP gateway. fix 466
This commit is contained in:
Goffi
parent
c1cb70ac1a
commit
d2f4623b53
2 changed files with 215 additions and 0 deletions
214
doc/howto_email_gateway.rst
Normal file
214
doc/howto_email_gateway.rst
Normal file
|
|
@ -0,0 +1,214 @@
|
|||
.. _howto_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`).
|
||||
|
||||
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.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
Before configuring the Email Gateway, ensure you have:
|
||||
|
||||
1. Libervia backend installed and running (see :ref:`installation`)
|
||||
2. An XMPP server configured with component support (such as Prosody, Ejabberd, Openfire,
|
||||
Tigase, MongooseIM, etc).
|
||||
|
||||
Configuration Steps
|
||||
-------------------
|
||||
|
||||
1. **Configure XMPP Server Components**
|
||||
|
||||
Add the Email Gateway as an XMPP component on your server:
|
||||
|
||||
*For Prosody:*
|
||||
|
||||
.. code-block:: lua
|
||||
|
||||
-- Add to /etc/prosody/prosody.cfg.lua
|
||||
Component "email.example.org"
|
||||
component_secret = "your_unique_secret"
|
||||
|
||||
*For Ejabberd:*
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# Add to /etc/ejabberd/ejabberd.yml
|
||||
hosts:
|
||||
- "example.org"
|
||||
|
||||
listen:
|
||||
-
|
||||
port: 5269
|
||||
module: ejabberd_service
|
||||
hosts:
|
||||
"email.example.org":
|
||||
password: "your_unique_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).
|
||||
|
||||
2. **Create Libervia Profile for Email Gateway**
|
||||
|
||||
Use the Libervia CLI to create the gateway profile:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ li profile create email-gateway \
|
||||
-j email.example.org \
|
||||
-p "" \
|
||||
-x "your_unique_secret" \
|
||||
-C email-gateway \
|
||||
-A
|
||||
|
||||
This creates a profile named `email-gateway` with:
|
||||
|
||||
- JID: `email.example.org`
|
||||
- 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**
|
||||
|
||||
Users must register their email credentials through the gateway's registration
|
||||
interface (XEP-0100). This is done from an XMPP client that supports gateway
|
||||
registration.
|
||||
|
||||
To register your email account using the Libervia CLI, run:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ li gateway register -cp your_user_profile email.example.org
|
||||
|
||||
**Registration Fields**
|
||||
|
||||
When prompted, you'll need to provide the following information:
|
||||
|
||||
User Name
|
||||
Display name for sent emails (e.g., "Louise")
|
||||
|
||||
User Email
|
||||
Email address used in the "From" field when sending messages
|
||||
|
||||
IMAP Host
|
||||
IMAP server hostname or IP address (e.g., "imap.example.com")
|
||||
|
||||
IMAP Port
|
||||
Port number for IMAP connection (default: 993)
|
||||
|
||||
IMAP Username
|
||||
Username for IMAP authentication
|
||||
|
||||
IMAP Password
|
||||
Password for IMAP authentication
|
||||
|
||||
SMTP Host
|
||||
SMTP server hostname or IP address (e.g., "smtp.example.com")
|
||||
|
||||
SMTP Port
|
||||
Port number for SMTP connection (default: 587)
|
||||
|
||||
SMTP Username
|
||||
Username for SMTP authentication
|
||||
|
||||
SMTP Password
|
||||
Password for SMTP authentication
|
||||
|
||||
**Important Notes**
|
||||
|
||||
- Ensure your IMAP/SMTP servers are accessible from the Libervia backend
|
||||
- The IMAP server must support the IDLE extension for real-time notifications
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
---------------
|
||||
|
||||
.. list-table::
|
||||
:widths: 30 70
|
||||
:header-rows: 1
|
||||
|
||||
* - Issue
|
||||
- Solution
|
||||
* - XMPP component connection failed
|
||||
- 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.
|
||||
“email.example.org” in Prosody must match the JID you set when creating the
|
||||
Libervia profile).
|
||||
* - User registration fails
|
||||
- * Check the IMAP/SMTP credentials and make sure the servers are reachable from the
|
||||
Libervia host.
|
||||
* Verify that the IMAP server supports the **IDLE** extension (required for
|
||||
real‑time notifications).
|
||||
* If you use self‑signed certificates, add them to the system trust store.
|
||||
* - Email not received
|
||||
- * Confirm the user’s email credentials (you can re-register to check).
|
||||
* Check Libervia Backend logs to ensure that the IMAP connection succeeded.
|
||||
* Verify that messages are arriving in the user’s INBOX.
|
||||
* - “DBus not launched” error
|
||||
- Follow :ref:`installation_dbus` instructions for headless servers – the
|
||||
Libervia backend relies on D‑Bus to run.
|
||||
* - Attachments not appearing
|
||||
- The Email Gateway can *retrieve* attachments, but does not yet deliver them with
|
||||
outgoing messages (feature work in progress).
|
||||
* - Encrypted emails not working
|
||||
- “Gateway Relayed Encryption” is a work‑in‑progress extension (not yet an official XEP).
|
||||
Use a client that implements this specification.
|
||||
* - Mailing lists not converted
|
||||
- Verify that the incoming e‑mail contains a **valid “List‑ID”** header. The value
|
||||
must match the format expected for PubSub node creation.
|
||||
|
||||
.. note::
|
||||
|
||||
The Email Gateway is under active development. Some features may have limitations.
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
- For Libervia components overview: :ref:`components`
|
||||
|
|
@ -24,6 +24,7 @@ You can follow this documentation to learn more on it, or join our official XMPP
|
|||
:maxdepth: 3
|
||||
|
||||
installation.rst
|
||||
howto_email_gateway.rst
|
||||
overview.rst
|
||||
configuration.rst
|
||||
encryption.rst
|
||||
|
|
|
|||
Loading…
Reference in a new issue