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

    -- Add to /etc/prosody/prosody.cfg.lua
Component "email.example.org"
    component_secret = "your_unique_secret"

    For Ejabberd:

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

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

    $ 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

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 Launching D‑Bus (on servers) 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