.. _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`
