# Mail services

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.

## Mail delivery

The `Mail` class is a mail delivery object which manages to contact a Mail Transport Agent 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 `set-mta-address` method. The class implements the recipient address syntax as specified by RFC822.

## Simple mail example

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

# 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

An empty message is sent to @domain.org. By default, the subject is initialized to `"no subject"`.

## Recipient address format

RFC822 defines the recipient address format. The simplest one is a local user or a qualified name with a domain. The `Mail` object takes care of detecting the presence of the `<` and `>` 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.

mail:to "me" mail:to "<me>" mail:to "me@domain.org" mail:to "<me@domain.org>" mail:to "user <me@domain.org>, other <other@domain.org>"

The `to` 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 `','` is used as the address separator. The `cc` method adds one or several addresses to the recipients copy list. This list is also added in the header. The `bcc` method adds one or several addresses to the recipient blind copy list. This list is not included in the header.

## Message content

The message is built by specifying the subject and filling the message buffer. The `subject` method take a string argument to be used as the message subject. The `add` and `addln` methods add one or several literals to the message buffer. The `addln` 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 `write` method of an output stream.

# 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"

## Message delivery

The `send` method contacts the MTA and request a message delivery. Example 3303.als illustrates a complete use of the `Mail` class.

# 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