category-group: email
layer(s): 1, 4, 9, 11

header file(s): z_email.h, z_emailaddr.h

synopsis.
The Z Directory group "email" (or "e-mail") is related to the group "address", Since an e-mail address is a type of address. However, ever since the creation of tools and devices such as ethernet, TCP/IP, and the World-Wide Web in the 1970's, 1980's, and 1990's, e-mail has become quite important. Hence, although the address group can be considered to be the roots of the e-mail group, the only e-mail object directly related to it is the email address object. With this class you can send e-mails.
As of build #18, the non-SSL e-mail components are fully functional. However, this document has not been updated.
Please contact Vettrasoft and notify us that you are reading this! We would then clean up this document. Thanks.

OLD NOTES: There is a cluster of objects in this group relating to e-mail. AS OF THIS WRITING (June 2012), ALL OBJECTS IN THE GROUP "EMAIL" ARE UNSUPPORTED:

     email_acct_o
     email_sender_o
     mapi_store_o
     email_header_o
     email_msg_o
     email_store_axiom_o

All of these components are experimental and under review and/or development. You can find their definitions in header files (in the Z Directory big bucket of header files), but they are, until further notice, not supported and not documented.

Delivery of e-mail is done entirely by the email address object, in the group "address", as mentioned above. The fate of the other objects (in the list above) will be determined at a later date.

Note that the email address object requires a pre-existing e-mail delivery-transport system. That is, what is available here is akin to what is found in an e-mail client such as Eudora or Outlook: You'll still need a functional mail server to actually forward messages into the e-mail system. Just like writing a letter on paper, the Z Directory e-mail tools can help you package up the message and throw it into a mailbox - but the mailman still must carry the mail.

classes in this group: email_o, emailacct_o, emailheader_o, mta_session_o, popmail_session_o,
                                      smtp_session_o, massmail_o, webmail_o

support/internal classes: emailstore_axiom_o

description.
Z Directory e-mail has undergone a long evolution. Currently, all the available functionality can be found in the email_address_o class. This class object, like other address classes, is directly descended from the address object ( address_o ). Like its kin the postal address object, you can assign a value to it and the string you use to do that will be stored 'raw and unchecked' in an internal storage area called "free text". This may differ from the actual address. The "free text" is an alternative 'format', so that you can retrieve the original string you assign to these address objects.

With an email_address_o , after assigning it a value - that is, assigning the object-instance an e-mail address, you can use the member function send_message() to fire off some text to the given e-mail address. However logical this may seem at first, this methodology does not conform to the Z Directory transport architecture: an address by itself is not a transport device, so it is not supposed to know how to 'send a message'. However, this function call has become so engrained over the years that you can do it this way. This will probably change in the future. Vettrasoft will give plenty of advance warning of any such changes.

Currently and in the past, the focus of the work that the email group was to send mail. There is much more that can be done with e-mail. Unfortunately, as of this writing, the official Z Directory functionality stops there. The remainder of this section discusses aspects of e-mail that is planned to be implemented in the future.

Mail stores.
In addition to an e-mail address, there are "e-mail stores", eg, repositories that hold e-mail. These are called MTAs - Mail Transport Agents . They can be based on different protocols, such as IMAP or POP-3. They are represented by "e-mail store" ( email_store_axiom_o, mapi_store_o ) class objects.

compoenents of e-mail messages.
Since with e-mail you can send a picture, as an attachment, without text per se, the item delivered is not really a "letter", so we will refer to the contents of e-mails simply as a "message", as opposed to letter, text, or something else. Objects that handle the message body of an e-mail are delegated to the email_msg_o class. Also for any given e-mail, the "header" part contains information about the e-mail message: its sender, its recipient, and a list of intermediate delivery points. For this we have the email_header_o class.

note.
The correct layering (the number given in the square brackets), if the Z Directory methodology algorithm was strictly adhered to, would be this:

    [4] z_emailmess.h
    [5] z_emailaxiom.h
    [6] z_emailmapi.h
    [6] z_emailacct.h
    [9] z_emailaddr.h
    [9] z_email.h

For example, 'z_emailaxiom.h' would be in layer 5, since 'email_store_axiom_o' contains and uses [layer 4] 'email_msg' object. Similarly, the 'mapi_store_o' class is sub-classed from 'email_store_axiom_o', so its header file ('z_emailmapi.h') would normally be in layer 6. However, the spread (layers 4 to 6) has been compressed into one layer, which is 4. Thus, all e-mail components are in either 4 or 9. The latter is used for the exception 'email_address_o' class and an accompanying class, 'email_sender_o'.

examples.
For an example of how to send an e-mail, please see the reference manual page for the email address object. The following example is a sample of what code utilizig the e-mail components currently under development might look like. This code is "experimental" - no guarantees are made as to whether it works or not (actually, we doubt it). This is not meant to be a working example.

#include "z_email.h"

void func (int);

void main()
{
    int idx, ie = 0;
    email_acct_o ems(name, passw, server, protocol, zt_mail_OPENSTATIC);

    for (idx = 0; !ie; idx++)
    {
        const email_header_o &hdr = ems.next_message(&ie);
        if (ie) break;
        std::cout << "** Message " << idx << ":"            << "\n";
        std::cout << "Subject:"    << hdr.subject().data()  << "\n";
        std::cout << "Sender:"    << hdr.sender().data()    << "\n";
        std::cout << "Id:"        << hdr.remote_id().data() << "\n";
        if (hdr.subject() == "TEST")
        {
            email_msg_o &msg  = ems.read_message();
            string_o    &body = msg.text();
        }

        std::cout << std::endl;
    }

    func(ems.get_id());
}

void func (int s_store_id)
{
    email_acct_o ems(s_store_id);
    email_acct_o ems2(name, passw, server, protocol, zt_mail_OPENSTATIC);
}