@callback auth_mechanisms(state()) :: [String.t()]

SASL mechanisms to offer in the EHLO reply, upper-case, for example ["PLAIN", "SCRAM-SHA-256"]. Called only when the session offers AUTH, and on every EHLO and AUTH, so the list may depend on the state. Without this callback, no mechanism is offered.

@callback handle_auth(
  mechanism :: String.t(),
  initial_response :: binary() | nil,
  state()
) :: auth_result()

AUTH with an offered mechanism. initial_response is the decoded initial response, "" when the client sent =, and nil when it sent none.

@callback handle_auth_abort(state()) :: state()

The exchange ended without a result: the client cancelled with *, sent an invalid response, or the session ended.

@callback handle_auth_response(response :: binary(), state()) :: auth_result()

The client's (decoded) response to a challenge.

@callback handle_data(Sovite.SMTP.Server.Session.transaction(), state()) :: result()

DATA, when the transaction has at least one recipient. Accept to get 354. With BDAT, called for the first chunk.

@callback handle_data_abort(reason :: atom(), state()) :: state()

The message was abandoned by the session: :too_large, :bare_lf, :bare_cr, :timeout, :closed (the connection ended), or :reset (the transaction was reset between BDAT chunks; handle_rset/1 follows).

@callback handle_data_chunk(iodata(), state()) ::
  {:ok, state()} | {:reply, Sovite.SMTP.Reply.t(), state()}

Decoded message content, in order. Returning a reply aborts the message: the rest of the data is read and discarded, the reply is sent after the final dot, and handle_data_end/2 is not called.

@callback handle_data_end(Sovite.SMTP.Server.Session.transaction(), state()) :: result()

The final dot, or BDAT ... LAST. Accept only once the message is safely stored.

@callback handle_etrn(Sovite.SMTP.Command.etrn_node(), state()) :: result()

ETRN (RFC 1985), only when enabled: start delivering the mail queued for node. Accept to get 250 Queuing started; reply 251 when no mail is waiting, 253 with the number of messages, 458 when it cannot be done now, and 459 when the node is not allowed.

@callback handle_greet(early_input :: binary(), state()) ::
  {:ok, state()} | {:close, Sovite.SMTP.Reply.t(), state()}

Called just before the greeting with what the client sent before it: "" unless the greeting was delayed and the client did not wait. Return {:close, reply, state} to refuse the client instead.

@callback handle_helo(:ehlo | :helo | :lhlo, name :: String.t(), state()) :: result()

EHLO, HELO, or (in an LMTP session) LHLO. The name is a valid domain or address literal.

@callback handle_mail(
  sender :: String.t(),
  Sovite.SMTP.Server.Session.mail_params(),
  state()
) :: result()

MAIL FROM. sender is "" for the null reverse-path.

@callback handle_rcpt(
  recipient :: String.t(),
  Sovite.SMTP.Server.Session.rcpt_params(),
  state()
) ::
  result()

RCPT TO, after the session checked the recipient limit. params has the DSN parameters, when the session offers DSN.

@callback handle_rset(state()) :: state()

RSET, or a new EHLO/HELO that resets the transaction.

@callback handle_tls(Sovite.TLS.info(), state()) :: state()

The connection is now encrypted (after STARTTLS). The session has been reset: forget the EHLO name and anything else learned before.

@callback handle_vrfy(argument :: String.t(), state()) :: result()

VRFY, only when enabled. Without this callback the reply is 252.

@callback init(Sovite.SMTP.Server.Session.connection(), opts :: term()) ::
  {:ok, state()}
  | {:pause, non_neg_integer(), state()}
  | {:close, Sovite.SMTP.Reply.t(), state()}

Called when the connection opens, before the greeting. Return {:close, reply, state} to refuse the client (typically with 554), or {:pause, milliseconds, state} to wait that long before the greeting (see "Greeting delay" in Sovite.SMTP.Server.Session).

Called again, after terminate/2, when a proxy names another client with XCLIENT; a pause is then skipped.

@callback terminate(reason :: term(), state()) :: any()

The session ended.