Using the Mail Classes

The following are the general steps used to create an outbound email:

1. Create an MCFOutboundEmail object

2. Set the usual properties for an email, such as the From, Subject, Recipients, and Text properties.

3. If necessary, set the parts of the email using MCFMultipart and MCFBodyPart classes.

4. Use the Send method to send the email.

The MCFPart and MCFEmail classes provide the common functionality for the MCFBodyPart and MCFOutboundEmail (and MCFInboundEmail) classes, respectively. In general, you never need to use the MCFPart or MCFEmail classes directly in your PeopleCode programs. However, in rare cases you may use these classes if you want to extend the application package.

The SMTPSession class encapsulates all the session parameters that can be set in a Simple Mail Transfer Protocol (SMTP) session. Each MCFOutboundEmail object points to one SMTPSession object. In most cases, the parameters for the SMTP session are set from values found in the application server configuration file (psappsrv.cfg). However, you can also set these parameters by creating an SMTPSession object, setting the desired parameters, then creating an MCFOutboundEmail object.

For convenience, all SMTP attributes are also directly accessible from the MCFOutboundEmail class, so you don't need to create an SMTPSession object when you're sending just one email.

When you want to send many emails in a single SMTP session, you don't have to set the SMTP session parameter in each and every email. For this case, you can create a single SMTPSession, using either the default settings or explicitly setting the desired parameters, then use the CreateOutboundEmail method of SMTPSession object to create all the MCFOutboundEmail objects. This way all the MCFOutboundEmail objects use the same SMTP session parameters. After specifying the value of all the parameters for all the MCFOutboundEmail objects, use the SendAll method of SMTPSession object to send all the emails in one SMTP session.

All the application classes mentioned above hold all the data until one of the Send methods is called. The Send methods connect to the mail server using a JavaMail API that sends the mail.

Since all communication to the mail server happens when a Send method is called, errors are only reported when the Send method returns. The return value indicates the success or the failure of the send process. In case of failure, you can query the MCFOutboundEmail application class for the details of the error. The error details are available in properties such as MessageSetNumber, MessageNumber, ErrorDescription, ErrorDetails, and so on.

There is an SMTP extension that supports Delivery Status Notifications (DSN) defined in RFC 1891. This may or may not be supported by the user's Mail Transport Agent (MTA). The acknowledgements do not indicate whether the user reads the message, they only acknowledge receipt of the message by their mail server. It is possible that the mail server throws the message away as spam and the end user never actually receives the email. To get such notifications, set the StatusNotifyOptions and StatusNotifyReturn properties, as in the following example:

&email.StatusNotifyOptions  = "SUCCESS,FAILURE";
&email.StatusNotifyReturn = "HDRS";

You can use the IsReturnReceiptReqd property to specify if a return receipt should be sent when the mail server receives and opens the email. This property only works if the underlying SMTP server supports this feature. The following is an example of using this property:

&email.IsReturnReceiptReqd = True;

There is no SMTP standard for message priority. Most email applications use an X−Priority value of 3 for messages with "normal" priority. More important messages have lower values and less important messages have higher values. In most cases, urgent messages have an X−Priority value of 1. The priority code used with the Mail classes, and set in the headers are as follows:

1. Highest Priority

2. High Priority

3. Normal

4. Low Priority

5. Lowest Priority

The default value is 3, that is, normal priority.

Different email programs render these different values in a variety of ways, usually using some kind of colored symbols or arrows.

Set the priority for an email using the Priority property. The following is an example:

&Email.Priority = 2;

Both MCFBodyPart and MCFEmail objects are used for both inbound and outbound email. The following sections specify which methods and properties are generally used for inbound, and which are used for outbound, for the different objects.