reactive-mail-server/backend/src/main/java/com/mailserver/smtp/SmtpBackend.java

package com.mailserver.smtp;

import java.util.List;

/**
 * What the SMTP server asks the rest of the application. All methods may block (database, DNS):
 * the server calls them on a worker thread, never on the network event loop.
 */
public interface SmtpBackend {

    /** Where a recipient goes, decided at RCPT TO. */
    enum Route {
        /** A mailbox of ours (or the catch-all mailbox) — store it. */
        LOCAL,
        /** Someone else's address, sender is logged in — queue for delivery. */
        OUTBOUND,
        /** Address of our domain that does not exist. */
        UNKNOWN_USER,
        /** Someone else's address and the sender is not logged in: we are not an open relay. */
        RELAY_DENIED,
        /** Someone else's address, outbound delivery is switched off on this server. */
        OUTBOUND_DISABLED
    }

    record Recipient(String address, Route route) {
    }

    record Envelope(String remoteIp, String helo, String mailFrom, String authenticatedUser, List<Recipient> recipients) {
    }

    /** true — the address and password belong to an active mailbox. */
    boolean authenticate(String username, String password);

    Route route(String recipient, String authenticatedUser);

    /**
     * Stores or queues the message for every recipient. Returns normally only when the message is safe
     * (stored or queued) — then the client gets 250. Any exception → 451, the client will retry.
     */
    void accept(Envelope envelope, byte[] message) throws Exception;
}