Fediversity

Feature Specification: Component smtp

Created: 2026-10-07

Status: Implemented

Input: Reconstructed from the code of core/components/shared/smtp/ and its wiring in the setups at 14504f80d, pull requests #1383, #1822, #1835 and #1852.

User Scenarios & Testing (mandatory)

User Story 1 - Relay the mail of a group (Priority: P1)

The applications of a group send mail. The smtp component runs maddy as the relay of the group and provides smtp (see smtp). The setup gives each application a submission account with a generated password.

Why this priority: Without a relay, no application can send mail.

Independent Test: A provider contract test, VM tests of DKIM and of the mail reports, and a unit test of the routing.

Acceptance Scenarios:

  1. Given authelia or lldap machines, When the setups evaluate, Then the relay has an account for each, with the senders of the mail domains.

User Story 2 - Serve submission over TLS (Priority: P2)

Clients submit over TLS, with a certificate from the internal PKI or ACME (see ssl). maddy loads a renewed certificate.

Why this priority: TLS protects the submission passwords.

Independent Test: The provider contract test.

Acceptance Scenarios:

  1. Given a renewed certificate, Then maddy loads it.

User Story 3 - Alert on bounced mail (Priority: P3)

maddy reports a bounce only in its journal. The node ships the journal to the log store, and a telemetry rule alerts on bounces.

Why this priority: Mail flows without the alert.

Independent Test: No check covers the alert.

Acceptance Scenarios:

  1. Given a bounced message, Then the bounce alert fires.

Edge Cases

  • A group without an smtp machine gives no notifier to authelia and no reset mail to lldap.

Requirements (mandatory)

Functional Requirements

  • FR-001: The component MUST provide smtp and MUST use maddy.
  • FR-002: The component MUST request spiffe, so that maddy reads its rotated passwords from OpenBao.
  • FR-003: The component MUST NOT request forward-auth, because the relay has no web UI.
  • FR-004: The setup MUST configure maddy, the accounts and the passwords through the smtp resource.

Key Entities

  • Submission account: One per sending application, with a password in OpenBao.

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: The provider contract test, the DKIM and report VM tests, and the unit tests of the routing and the lldap mail wiring pass.

Assumptions

  • The hosting-provider and operator groups each run a relay.
  • The component has no icon.
  • The provider, with the external relay, is in the smtp resource.

Known Deviations

None.