<?xml version="1.0" encoding="UTF-8"?>

<!-- ====================================================================== -->
<!-- = chapter-2.xml                                                      = -->
<!-- = standard network module guide - chapter 2                          = -->
<!-- ====================================================================== -->
<!-- = This  program  is  free  software; you  can redistribute it and/or = -->
<!-- = modify it provided that this copyright notice is kept intact.      = -->
<!-- = This program is distributed in the hope that it will be useful but = -->
<!-- = without  any  warranty;  without  even  the  implied  warranty  of = -->
<!-- = merchantability or fitness for  a  particular purpose. In no event = -->
<!-- = shall  the  copyright  holder be liable for any  direct, indirect, = -->
<!-- = incidental  or special  damages arising  in any way out of the use = -->
<!-- = of this software.                                                  = -->
<!-- ====================================================================== -->
<!-- = copyright (c) 2005-2007 - amaury darsch                            = -->
<!-- ====================================================================== -->

<chapter module="net" number="2">
  <title>Mail services</title>

  <p>
  This chapter is dedicated to the mail delivery subsystem, which is
  part of the standard network module. The mail delivery is built
  around a class that handle that can operate as a simple MTA.
  </p>

  <!-- mail delivery -->
  <section>
    <title>Mail delivery</title>

    <p>
    The <code>Mail</code> class is a mail delivery object which
    manages to contact a <em>Mail Transport Agent</em> or MTA, in
    order to deliver a message to one or several recipients. By
    default, the object contacts the local MTA, but this behavior can
    be changed with the <code>set-mta-address</code> method. The class
    implements the recipient address syntax as specified by RFC822.
    </p>

    <!-- simple mail -->
    <subsect>
      <title>Simple mail example</title>

      <p>
      At construction, the instance is empty. Only the recipient
      address needs to be specified. The <code>send</code> method send
      the message by contacting the MTA. If an error occurs, an
      exception is raised.
      </p>

      <example>
      # get the network module
      interp:library "afnix-net"

      # create an empty mail
      const mail (afnix:met:Mail)

      # add the recipient address
      mail:to "me@domain.org"

      # send the message
      mail:send
      </example>

      <p>
      An empty message is sent to 
      <mail address="@domain.org">@domain.org</mail>. By default,
      the subject is initialized to <tt>"no subject"</tt>.
      </p>
    </subsect>

    <!-- recipient address format -->
    <subsect>
      <title>Recipient address format</title>

      <p>
      RFC822 defines the recipient address format. The simplest one is
      a local user or a qualified name with a domain. The
      <code>Mail</code> object takes care of detecting the presence of
      the <code>&lt;</code> and <code>&gt;</code> characters. If a
      string precedes the address, the enclosed address is used to
      communicate with the MTA, but the original one is placed in the
      header. The following example illustrates various address format.
      </p>

      <example>
      mail:to "me"
      mail:to "&lt;me&gt;"
      mail:to "me@domain.org"
      mail:to "&lt;me@domain.org&gt;"
      mail:to "user &lt;me@domain.org&gt;, other &lt;other@domain.org&gt;"
      </example>

      <p>
      The <code>to</code> method adds an address to the direct
      recipient list. Several call to this method or several address
      in one call can be made. In the case of multiple addresses in
      one call, a coma <code>','</code> is used as the address
      separator. The <code>cc</code> method adds one or several
      addresses to the recipients copy list. This list is also added
      in the header. The <code>bcc</code> method adds one or several
      addresses to the recipient <em>blind copy list</em>. This list is
      not included in the header.
      </p>
    </subsect>

    <!-- message content -->
    <subsect>
      <title>Message content</title>

      <p>
      The message is built by specifying the subject and filling the
      message buffer. The <code>subject</code> method take a string
      argument to be used as the message subject. The <code>add</code>
      and <code>addln</code> methods add one or several literals to
      the message buffer. The <code>addln</code> method adds a
      new-line character at the end. Because literals are used with
      this method, multiple arguments can be used as well as native
      representation. This method behaves like the <code>write</code>
      method of an output stream.
      </p>

      <example>
      # set message subject
      mail:subject "a simple mail demo"
      # add a line in the message buffer
      mail:add   "This line is a text added to the message"
      mail:addln "a simple number: " 123 "is automatically converted"
      </example>
    </subsect>

    <!-- message delivery -->
    <subsect>
      <title>Message delivery</title>

      <p>
      The <code>send</code> method contacts the MTA and request a
      message delivery. Example <file>3303.als</file> illustrates a
      complete use of the <code>Mail</code> class.
      </p>
      
      <example>
      # send an email to yourself

      # get the libraries
      interp:library "afnix-sys"
      interp:library "afnix-net"

      # get your user name
      const user-name (afnix:sys:get-user-name)

      # prepare the mail
      const mail (afnix:net:Mail)
      mail:to      user-name
      mail:subject "hello from afnix example"
      mail:addln   "This is a generated message from the Afnix"
      mail:addln   "mail object - Enjoy the ride"
      mail:addln   "The Afnix team"

      # send the mail
      mail:send
      </example>
    </subsect>
  </section>
</chapter>
