smtp.pl -- Send E-mail through SMTP

This module provides a simple means to send E-mail from a Prolog application. Here is a simple example:

send_message(Out) :-
        format(Out, 'Hi Alice,\n\n', []),
        format(Out, 'Want to go out tonight?\n\n', []),
        format(Out, '\tCheers, Bob\n', []).


?- smtp_send_mail('alice@wonderland.com',
                  send_message,
                  [ subject('Tonight'),
                    from('bob@wonderland.com')
                  ]).

This library currently supports good old  SMTP, encrypted and authorized
ESMTP. Both SSL/TLS and STARTTLS  encryption is supported. Authorization
is supported using =PLAIN= and =LOGIN= methods.

Data is currently being sent using the =DATA= keyword.

@tbd    Support more advanced data transport extensions such as sending
        MIME messages.

 smtp_send_mail(+To, :Goal, +Options)

Send mail using SMTP. To is the e-mail address of the receiver. Options:

• smtp(+Host) the name or ip address for smtp host, eg. swi-prolog.org
• from(+FromAddress) atomic identifies sender address. Provides the default for header(from(From)).
• date(+Date) Set the date header. Default is to use the current time.
• subject(+Subject) atomic: text for 'Subject:' email header
• auth(User-Password) authentication credentials, as atoms or strings.
• auth_method(+PlainOrLoginOrNone) type of authentication. Default is default, alternatives are plain and login
• security(Security) one of: none, ssl, tls, starttls
• content_type(+ContentType) sets Content-Type header
• mailed_by(By) add X-Mailer: SWI-Prolog <version>, pack(smtp) to header iff By == true
• header(Name(Val)) add HName: Val to headers. HName is Name if Name's first letter is a capital, and it is Name after capitalising its first letter otherwise. For instance header(from('My name, me@server.org')) adds header "From: My name, my@server.org" and header('FOO'(bar)) adds "FOO: bar"

Defaults are provided by settings associated to this module.

Listens to debug(smtp) which for instance reports failure to connect, (computation fails as per non-debug execution).

Arguments:

To	- is an atom holding the target address
Goal	- is called as call(Goal, Stream) and must provide the body of the message.

 hostname(-HostName, +Options) is det[private]

Get the hostname used to identify me.

 do_send_mail(+In, +Out, +To, :Goal, +Options) is det[private]

Perform the greeting and possibly upgrade to TLS. Then proceed using do_send_mail_cont/5.

Note that HELO is the old SMTP greeting. Modern systems greet using EHLO, telling the other side they want to speak RFC 1870 rather than the old RFC 821.

To be done

- Fall back to RFC 821 if the server does not understand EHLO. Probably not needed anymore?

 starttls(+In0, +Out0, -In, -Out, +LinesIn, -LinesOut, +Options)[private]

To be done

- Verify starttls is in Lines.

 auth(+In, +Out, +From, +Lines, +Options)[private]

Negotiate authentication with the server. Currently supports the plain and login authentication methods. Authorization is sent if the option auth is given or the settings user and password are not the empty atom ('').

Arguments:

Lines

- is the result of read_ok/3 on the EHLO command, which tells us which authorizations are supported.

 auth_supported(+Lines, -Supported)[private]

True when Supported is a list of supported authorization protocols.

 sock_send(+Stream, +Format, +Args) is det[private]

Send the output of format(Format, Args) to Stream and flush the stream.

 header_options(+Out, +Options) is det[private]

Send SMTP headers from provided Options. First adds some defaults, notably:

• If there is no header(from(From)) it uses the from(From) from Options.
• If there is no date(Spec) it adds date(Date).

 read_ok(+Stream, ?Code) is semidet[private]

 read_ok(+Stream, ?Code, -Lines) is semidet[private]

True if the server replies with Code. The version read_ok/3 returns the server comment lines, one atom per line. The numeric code has been stripped from the lines.