DOCSEARCHbyAlgolia
Submit Docs

LSMTPD Documentation

website·Indexed 30 days ago

https://lsmtp.nekonik.org

A lightweight and high-performance SMTP server designed to bridge email and message queues, featuring seamless AMQP integration. Built with the Rust toolchain, it is optimized for containers, VMs, and microservices architectures, enabling event-driven email processing by placing email messages into RabbitMQ queues.

Tokens
4.3K
Snippets
15
Records
43
Agent score
50%

What's inside LSMTPD

  1. Overview of LSMTPD features

    LSMTPD is a minimal and efficient SMTP server designed for low resource consumption, making it suitable for deployment in containers, virtual machines (VMs), and microservices. Its primary functionality is to integrate SMTP traffic with AMQP message brokers, converting incoming emails into actionable events for downstream systems. The project is open source, allowing for code inspection and community contribution.

  2. Overview of LSMTPD

    LSMTPD (Lightweight SMTP Daemon) is a high-performance, minimalistic SMTP server written in Rust. Its primary purpose is to act as a bridge between email and message queues by accepting incoming SMTP email messages and forwarding them directly into AMQP (Advanced Message Queuing Protocol) systems. It is designed for distributed systems and microservices that need to process incoming emails as events without the complexity of a full Mail Transfer Agent (MTA) like Postfix or Exim.

  3. Overview of LSMTPD

    LSMTPD (Lightweight SMTP Daemon) is a minimal, receive-only SMTP server written in Rust. Its primary purpose is to ingest email via SMTP and forward it directly into an AMQP queue or exchange. Unlike traditional MTAs like Postfix or Exim, it does not support outbound mail, mail storage, or spam filtering, making it more suitable for containerized or microservice environments where the goal is simply to push received mail into a message broker.

  4. LSMTPD Repository Layout Overview

    LSMTPD uses a modular architecture where each component has a single responsibility to minimize coupling. The project is structured as follows:

    • src/: Application source code
    • packages/: Additional packages
    • target/: Rust build output (automatically generated by Cargo)

    Core Dependency Hierarchy: main.rs coordinates startup and depends on state, handler, queue, models, and errors.

    LSMTP/
├── Cargo.toml
├── src/
│   ├── main.rs
│   ├── state.rs
│   ├── errors.rs
│   ├── handler/ (SMTP protocol logic)
│   ├── models/  (Data structures)
│   └── queue/   (Message delivery)
└── target/     (Build artifacts)

  5. Message Processing and AMQP Integration

    Incoming messages are parsed and queued into an internal tokio::sync::mpsc channel. A dedicated worker task consumes these messages and publishes them to a configured AMQP exchange. This architecture provides backpressure handling to maintain server responsiveness under high load.

  6. Understand the LSMTP RabbitMQ email message structure

    When building custom workers for LSMTP, messages are retrieved from the RabbitMQ queue as serialized JSON objects. Each message contains metadata about the SMTP transaction and the full email content. Note that email size must comply with your specific RabbitMQ configuration limits.
    {
    "timestamp": "2025-09-23T23:18:51.477629045+00:00",
    "message_id": "cf4c844f-a317-44f7-97a3-0aaa5be372e3",
    "client_address": "NEKO-NIK-Example",
    "recipients": ["<admin@nekonik.com>"],
    "email_content": "Email body / DATA part",
    "sender": "from-id@nekonik.org"
}

  7. Understand LSMTPD Connection Handling

    LSMTPD manages incoming SMTP client connections asynchronously using tokio::spawn to support thousands of concurrent sessions. To prevent idle or stuck connections from consuming resources, the server uses a timeout mechanism controlled by the MAX_TIMEOUT_SECS environment variable.

  8. Integrate SMTP traffic with AMQP brokers using LSMTPD

    LSMTPD provides seamless AMQP integration, allowing emails to flow directly into a message broker. This architecture transforms standard SMTP traffic into events that can be consumed and processed by other systems in a distributed environment.

  9. Understand the LSMTPD email processing workflow

    LSMTPD processes emails through a sequential lifecycle:

    1. Client Connection: A client connects via SMTP; LSMTPD spawns an async task using tokio::spawn with a 180-second idle timeout.
    2. SMTP Handshake: Client sends EHLO/HELO and the server responds with its SERVER_NAME.
    3. Envelope Setup: Client defines the sender via MAIL FROM and recipients via RCPT TO.
    4. Message Transfer: Client sends the DATA command and the email body. LSMTPD enforces basic SMTP formatting and size limits (returning error 552 if exceeded).
    5. Validation: LSMTPD verifies the presence of MAIL FROM, at least one RCPT TO, and the message body.
    6. Message Queueing: Valid messages are placed into a tokio::mpsc channel for a worker task to process.
    7. AMQP Delivery: The worker publishes the email to the configured AMQP exchange using the specified routing_key.
    8. Connection Close: The session ends via the QUIT command or server-side closure.

  10. Use LSMTPD for event-driven email processing and AMQP integration

    LSMTPD is designed for systems where email serves as an input signal or trigger for workflows. Unlike full-featured mail servers, it focuses exclusively on receiving mail and forwarding it directly to an AMQP message broker. This architecture is ideal for:

    • Event-Driven Workflows: Automatically creating support tickets, triggering CI/CD jobs, or feeding emails into spam-detection services.
    • Cloud-Native Architectures: Due to its minimal footprint, it is suitable for containerized environments (Docker, Kubernetes) and scales horizontally with AMQP infrastructure.
    • Bridging Legacy Systems: Connecting older SMTP-based tools to modern event-driven stacks by converting emails into queue messages.
    • Workflow Automation: Routing emails (e.g., order confirmations, alerts, form submissions) into queues for processing by billing systems, monitoring dashboards, or CRMs.
    • Simple Mail Ingestion: Providing a lightweight alternative to Postfix, Exim, or Sendmail for applications that only need to ingest incoming mail without needing outbound delivery or mailbox management.

  11. Install LSMTPD via the official APT repository

    LSMTPD can be installed on Debian-based systems using the official repository hosted at https://apt.nekonik.com. After adding the repository to the system, update the package list and install the lsmtpd package. Users may be prompted for initial settings during installation; if no prompts appear, configuration can be handled manually later.
    sudo apt update
sudo apt install lsmtpd

  12. Verify hardware and OS requirements for LSMTPD

    LSMTPD is a lightweight server with the following environment requirements:

    • Operating System: Linux. Debian/Ubuntu are recommended for packaged installations; other distributions are supported via Docker or source builds.
    • Architecture: x86_64 (amd64) or ARM64 (via Docker/source build).
    • Resources: Minimum 128MB RAM and 1 vCPU.