diff --git a/doc/howto_email_gateway.rst b/doc/howto_email_gateway.rst new file mode 100644 index 00000000..d0c21eab --- /dev/null +++ b/doc/howto_email_gateway.rst @@ -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` diff --git a/doc/index.rst b/doc/index.rst index 5e008369..a1764045 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -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