libervia-backend/doc/howto_email_gateway.rst

.. _howto_email_gateway:

=====================
How-To: Email Gateway
=====================

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 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
-------------

Before configuring the Email Gateway, ensure you have:

1. Libervia backend installed and working (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 = "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: "secret"

   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. **Configure the Email Gateway Component in Libervia**

   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:: toml

      [component.email_gateway]
      jid = "email.example.org"
      secret = "secret"

   The component profile is then created automatically on backend startup, and the
   component starts automatically. See :ref:`components` for details about the
   components configuration.

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 -c -p 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

   .. note::

      - Ensure your IMAP/SMTP servers are accessible from the Libervia backend
      - The IMAP server must support the IDLE extension for real-time notifications

Configuration
-------------

Besides the component configuration described above, no other configuration is needed:
the gateway uses user-specific data provided during registration.

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 in the Libervia
       configuration).
   * - User registration fails
     - *  Check the IMAP credentials and make sure the IMAP server is 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.
   * - Email not sent
     - *  Check the SMTP credentials and make sure the SMTP server is reachable from the
          Libervia host.
       *  Check the Libervia backend logs for the sending error.
   * - 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.