sys-svc-mail

Description

The sys-svc-mail role acts as the central mail orchestration layer in the Infinito.Nexus stack.
It wires together:

Stalwart as a full-featured mail server (when available),
msmtp as a lightweight sendmail-compatible SMTP client, and
an optional local SMTP relay (Postfix) for hosts without Stalwart.

For more background on the underlying protocol, see Simple Mail Transfer Protocol (SMTP) on Wikipedia.

Overview

This role provides a unified mail setup for your hosts:

If the host is part of the active mail provider's group (MAIL_PROVIDER), it:
- asserts the provider endpoint was preloaded (submission token present),
- and prepares the system to send emails through the provider using the sys-svc-mail-msmtp role.
If the host is not running Stalwart, it:
- optionally configures a local SMTP relay via sys-svc-mail-smtp (Postfix on localhost:25),
- and still configures msmtp as a sendmail-compatible client.

This makes sys-svc-mail the canonical entrypoint for “mail capabilities” on a node, abstracting away whether the actual delivery happens via Stalwart or a local relay.

Cosmos

The diagram places sys-svc-mail in the Infinito.Nexus cosmos: the components it deploys (capabilities), the central services it consumes (dependencies), and its outward reach (federation and bridged external networks).

flowchart LR
    subgraph role [sys-svc-mail 💻]
        svc_svc_mail["svc-mail"]
    end

Solid 1:1 edges are fixed relationships; dashed 0..1 edges are conditional (enabled only in matching deployments); red 0..0 edges are turned off in this role. Node markers show the role's deploy modes (💻 host, 🐳 compose, 🐝 swarm); ❌ marks a service that is explicitly turned off, and ⚙️ an Ansible role dependency declared in meta/main.yml.

Purpose

The main purpose of this role is to:

Provide a consistent mail-sending interface for all hosts in the Infinito.Nexus ecosystem.
Automatically choose between:
- Stalwart-backed delivery (with authentication tokens), or
- a local SMTP relay on localhost, depending on the presence of web-app-stalwart in the host’s groups.
Ensure that system services and applications can always send notifications (e.g. health checks, alerts, job results) without each role having to care about the underlying mail plumbing.

Features

🔄 Mail-provider integration (when available)
- Asserts the active provider's submission token was provisioned before configuring external mail.
- Routes outbound mail through the provider via sys-svc-mail-msmtp.
💡 Smart Fallback to Localhost
- If no web-app-stalwart is present, the role can configure a local Postfix-based SMTP relay via sys-svc-mail-smtp.
- Combined with sys-svc-mail-msmtp, this enables sending mail via localhost:25 without additional configuration in other roles.
📨 msmtp Client Configuration
- Delegates installation and configuration of msmtp to sys-svc-mail-msmtp.
- Supports both authenticated Stalwart delivery and unauthenticated localhost-based delivery.
🧩 Composable Design
- Uses internal run_once_* flags to avoid repeated setup.
- Cleanly integrates with the Infinito.Nexus stack and shared utilities.

Further Resources

Mail server:
- Stalwart: https://stalw.art/
- SMTP (protocol): https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol
SMTP client:
- msmtp: https://marlam.de/msmtp/
- msmtp on Wikipedia: https://en.wikipedia.org/wiki/Msmtp
Infinito.Nexus:
- Main repository: https://s.infinito.nexus/code
- Documentation: https://docs.infinito.nexus

Credits

Implemented by Kevin Veen-Birkenbach. Part of the Infinito.Nexus Project and maintained by Kevin Veen-Birkenbach. Licensed under the Infinito.Nexus Community License (Non-Commercial).

README.md Unescape Escape