# Module Netsmtp

    module Netsmtp: sig .. end

This is an interface for the Simple Mail Tranfer Protocol (SMTP) as specified by RFC 2821.

    exception Protocol_error

    exception Authentication_error

    exception Transient_error of int * string

    exception Permanent_error of int * string

    val tcp_port : int

default TCP port for SMTP
The class `client` implements the SMTP protocol. Client objects are created by

     new client in_ch out_ch

where `in_ch` is an input channel representing the input direction of the TCP stream, and where `out_ch` is an output channel representing the output direction of the TCP stream.

    class client : Netchannels.in_obj_channel -> Netchannels.out_obj_channel -> object .. end

    class connect : ?proxy:#Uq_engines.client_endpoint_connector -> Uq_engines.connect_address -> float -> client

`connect addr timeout`: Connects with the server at `addr`, and configure that I/O operations time out after `timeout` seconds of waiting.

    val auth_mechanisms : string list -> string list

If applied to `helo_response`, returns the list of AUTH mechanisms

    val authenticate : ?host:string ->
           ?tls_config:Netsys_crypto_types.tls_config ->
           ?tls_required:bool ->
           ?tls_peer:string ->
           ?sasl_mechs:Netsys_sasl.sasl_mechanism list ->
           ?sasl_params:(string * string * bool) list ->
           ?user:string ->
           ?authz:string -> ?creds:Netsys_sasl.credentials -> client -> unit

Authenticates the session:

- sends the EHLO string
- if the server supports TLS, and `tls_config` is set, the TLS session is started, and EHLO is repeated
- if AUTH support is announced by the server, one of the `sasl_mechs` is taken and used for authentication. If `sasl_mechs` is empty, this authentication step is skipped.

Options:

- `host`: the host name of the client
- `tls_config`: if set, TLS is tried on the connection
- `tls_required`: if set, it is even required that TLS is supported. If not, a `Netsys_types.TLS_error` exception is raised.
- `tls_peer`: the host name of the server (only needed for TLS, and only needed if the TLS configuration authenticates the server, or if the SNI extension is active)
- `sasl_mechs`: available SASL mechanisms (in order of preference). If you pass mechanisms, you'll normally also need to pass `user` and `creds`.
- `sasl_params`: parameters for SASL. A "digest-uri" parameter is always generated, and need not to be set
- `user`: the user name to authenticate as
- `authz`: the identity to act as (authorization name)
- `creds`: credentials

Regarding TLS: note that it is uncommon to require the server to be authenticated (opportunistic encryption), because servers often do not have certficicates from a regular trust center. You can get such a TLS config with

    let tls_config =
      Netsys_tls.create_x509_config
         ~peer_auth:`None
         (Netsys_crypto.current_tls())

SASL example:

    Netsmtp.authenticate
      ~sasl_mechs:[ (module Netmech_scram_sasl.SCRAM_SHA1);
                    (module Netmech_digest_sasl.DIGEST_MD5);
                  ]
      ~user:"tom"
      ~creds:[ "password", "sEcReT", [] ]
      client

    val sendmail : client -> Netmime.complex_mime_message -> unit

Sends the email to the receivers in the `to`, `cc`, and `bcc` headers. The SMTP server must support relaying of emails. See also `Netsendmail.sendmail`.

# Debugging

    module Debug: sig .. end