# 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

- For Libervia components overview: Libervia Components