Re: [bug-mailutils] Email

[Sergey Poznyakoff]

Hello,

To begin with, my apologies for answering that late.

The documentation is certainly the weekest point of the entire
package, we will hopefully fix it along with the major rewrite
of the mailbox library, as Alain has noticed.

Now to the questions:

> A) 
> 
> 1) Initialize library

Generally speaking, no special initialization sequence is
required. However you must register the mailbox formats
prior to use them. This is done using the following call
sequence:

list_t list; /* Temporary variable used to register the formats */

registrar_get_list (&list); /* Obtain the pointer to the registration
                               data */
list_append (list, mbox_record); /* Register UNIX mailbox format */
list_append (list, path_record); /* Register full path urls */
/* ..etc.. */

You will find the complete list of .*_record variables in the header
file include/mailutils/registrar.h (line 85 and below). Examples of
such initialization code may be found in any utility (function main).
The mail utility registers all the formats supported by the library
(see mail/mail.c, lines 225-234).

Also, the client programs that are using some special authentication
methods (e.g. MySQL, PAM, virtual passwords etc) and that are linked
against libmuauth library are required to register the needed
authentication methods and to initialize the library. This is done
by caling mu_auth_register_module() for every desired authentication
type and finally by calling mu_auth_init(). E.g., to register
sql authentication method:

mu_auth_register_module (&mu_auth_sql_module);
mu_auth_init ();

The macro MU_AUTH_REGISTER_ALL_MODULES() is a shortcut for registering
all existing authentication methods. These functions and methods are
declared in include/mailutils/mu_auth.h

> 2) Create a message

Use the function 

int message_create (message_t *pmsg, void *owner)

Upon successful completion `pmsg' will contain the pointer to the
message and the return value will be 0.

`owner' contains a pointer an object that `owns' this message, e.g.
mailbox, etc.

Notice that the message thus created is an `abstract message', i.e.
it lacks all the data and methods necessary for handling any concrete
type of the message. This should be set up separately. As an example
see mbox_get_message (mailbox/mbox/mbox.c:1157).

You should never use this function directly, unless you are writing
a support module for some new mailbox format. The message should
always be obtained from some other mailutils object. For example,
mailbox_get_message() obtains the message from a previously opened
mailbox, mime_get_message() returns the message associated with
the MIME object etc. The messages thus obtained are fully functional.

> 3) MIME Encode and attach a file to the message

As I've explained in one of my previous letters, messages are attached
to the MIME objects. So, you will first have to create a message
from the file. Use the message_create_attachment function for this:

int
message_create_attachment (const char *content_type,
                           const char *encoding,
                           const char *filename, message_t *newmsg)

The created message will be returned to the memory pointed by
`newmsg'.

A simplified scenario:

mime_t mime;
message_t msg;

mime_create (&mime, NULL, 0);
message_create_attachment (content_type, encoding, filename, &msg);
mime_add_part (mime, msg);

/* ... some time later .. */

mime_get_message (mime, &msg);

> 3) Specify To: / From: / Subject: for the message

/* Assuming msg is the object obtained from the call to
mime_get_message */

header_t hdr;

message_get_header (msg, &hdr);  /* Retrieve the header object */

/* If the last argument is 1, it means that any existing occurrence of
   the header in question will be replaced with the new value. This is
   useful for To:, Subject:, From: and the like.
   Otherwise, if it is 0, the new header will be added to the existing
   ones. This allows for multiple headers and is useful for Received:
   header */
header_set_value (hdr, "to", "md <address@hidden>", 1);
header_set_value (hdr, "from", "address@hidden", 1);
header_set_value (hdr, "subject", "Test message", 1);

The second argument to the header_set_value() is (a case-insensitive)
header name. The header file include/mailutils/header.h declares a set
of macros for the most useful header names. Using these, the above
example would look like:

header_set_value (hdr, MU_HEADER_TO, "md <address@hidden>", 1);
header_set_value (hdr, MU_HEADER_TO_FROM, "address@hidden", 1);
header_set_value (hdr, MU_HEADER_SUBJECT, "Test message", 1);

> 4) Send mail to SMTP server

First, register smtp_record as described in p. 1)
Then:

mailer_t mailer;

mailer_create (&mailer, "smtp://mx10.gnu.org");
mailer_open (mailer, MU_STREAM_RDWR); /* Open the SMTP channel in r/w
                                         mode */
mailer_send_message (mailer, msg, from, to);

Both `from' and `to' are objects of address_t type that specify
sender and recipient for the envelope of the message. If any of them
is NULL, the appropriate header from the message is used instead.

See mail.remote/mail.remote.c as an example.

> 5) Set password if email server prevents mail relay

Sorry, it is currently not implemented.

More on the questions B) later today.

Hope this helps.

Regards,
Sergey