@example
@code{/* Prefix @emph{mailer_} is reserved */}
@code{#include <mailutils/mailer.h>}

@end example

The API is still changing.

@deftypefun int mailer_create (mailer_t *, const char *)
@end deftypefun

@deftypefun void mailer_destroy (mailer_t *)
@end deftypefun

@deftypefun int mailer_open (mailer_t, int flags)
@end deftypefun

@deftypefun int mailer_close (mailer_t)
@end deftypefun

@deftypefun int mailer_send_message(mailer_t @var{mailer}, message_t @var{msg}, address_t @var{from}, address_t @var{to});

If from is not @var{NULL}, it must containg a single fully qualified
RFC2822 email address which will be used as the envelope from
address. This is the address to which delivery status notifications
are sent, so it never matters what it is set to until it REALLY matters.
This is equivalent to sendmail's @var{-f} flag.

The default for @var{from} is provided by the specific mailer.

If to is not @var{NULL}, then the message will be sent to the list of
addresses that it specifies.

The default for @var{to} is to use the contents of the standard "To:", "Cc:",
and "Bcc:" fields, this is equivalent to sendmail's @var{-t} flag.

Note: the previous implementation of mailer_send_message() was equivalent
to having both @var{from} and @var{to} be @var{NULL}.

@end deftypefun

@deftypefun int mailer_get_property (mailer_t, property_t *)
@end deftypefun

@deftypefun int mailer_get_stream (mailer_t, stream_t *)
@end deftypefun

@deftypefun int mailer_set_stream (mailer_t, stream_t)
@end deftypefun

@deftypefun int mailer_get_debug (mailer_t, debug_t *)
@end deftypefun

@deftypefun int mailer_set_debug (mailer_t, debug_t)
@end deftypefun

@deftypefun int mailer_get_observable (mailer_t, observable_t *)
@end deftypefun

@deftypefun int mailer_get_url (mailer_t, url_t *)
@end deftypefun

@subheading Some usage notes.

Some possible use cases the API must support are:

- original submission

 1 - fill in header addresses

 2 - mailer_send_message(mailer, msg, NULL, NULL);

   - - from will be filled in if missing,

   - bcc's will be deleted before delivery to a non-bcc address,

   - message-id and date will be added, if missing,

   - a to: or apparently-to: will be added if non is present (for RFC
     compliance)

- MTA-style .forward ( and sieve-style redirect )

 1 - get the envelope from of the message to be forwarded

 2 - mailer_send_message(mailer, msg, from, to)

- MUA-style bounce

 1 - add Resent-[to,from,....]

 2 - mailer_send_message(mailer, msg, NULL, to)

- DSN "bounce"

 1 - compose DSN

 2 - mailer_deliver(mailer, msg, address_t( "<>" ), to)

   Don't want mail loops, so the nul but valid SMTP address of <> is
   the envelope from.

@subheading The sendmail mailer.

/sbin/sendmail isn't always sendmail... sometimes its a sendmail-compatible
wrapper, so assume /sbin/sendmail understands only a recipient
list, -f, -F, -t, and -oi, these seem to be pretty basic. Cross fingers.

Pipe to "/sbin/sendmail -oi [-f from] <to|-t>", supplying -f if there
was a from, and supplying either the recipient list from the to,
or the -t flag.

Note: since the stdout and stderr of sendmail is closed, we have no
way of ever giving feedback on failure. Also, what should the return
code be from mailer_send_message() when sendmail returns 1? 1 maps to EPERM,
which is less than descriptive!

@subheading The SMTP mailer.

This is very rundamentary right now, all of what sendmail does must be
implemented.

Actually, I think some things (like date and message-id being inserted)
will be done by the receiving SMTP MTA. However, the specs say we
are supposed to canonicalize the mail before sending it, not rely
on the receiving SMTP agent to patch up our mail. Hmm... which is
the right way?

@subheading Non-RFC822 addresses.

An address that has no domain is not and RFC822 email address. What
do I do with them? Should the user of the API be responsible for
determining what is mean by email to "john" means? Or should the
be able to configure sendmail to decide globally what this means. If so, we
can pass the address to sendmail, but we have to decide for SMTTP! So,
right now these addresses are rejected. This could be changed.