d2f4623b53
This How-To complete installation instruction with an easy-to follow document to completely install the Email <=> XMPP gateway. fix 466
214 lines
7.4 KiB
ReStructuredText
214 lines
7.4 KiB
ReStructuredText
.. _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`
|