Tip 058: Creating and Sending Email

PeopleCode | Two approaches for creating an email message in PeopleCode.

A. Email Options

As a developer, you may be faced with a requirement that asks you to generate and distribute an email message to one user, or a specified list of users (perhaps controlled by a security Role – refer to Tip 043 for more details). If your email needs to be distributed to key system entities (such as employees, students, or customers) or if the fact of sending the email needs to be recorded, a better option would be the 3Cs ‘CommGen’ process (Communication Generation). This allows an email template to be defined and then distributed to the required people. The communication is also logged in the system.

In some cases, using the CommGen functionality is inappropriate or excessive for the requirement you have in mind. Perhaps you need to email a CSV file to a handful of internal staff members on a daily basis. Perhaps you need to advise a staff member of an outstanding item in a workflow process. Perhaps you’d like to email yourself a log file at the end of a process. Fortunately, PeopleCode provides you with a couple of options for generating emails.

Before we get into specifics, it’s worth noting that you must take great care with any email development. Make sure your development database does not contain real email addresses (and if they do, update them with your own email address or another ‘safe’ address). Also, if you are testing a process to send out bulk emails, always perform the initial tests on a small population. Every developer’s worst nightmare is sending out an inappropriate test message to 20,000 actual customers.

B. SendMail

The first option to generate an email is the traditional ‘SendMail’ function. This function tends to have a bad reputation with some PeopleSoft developers, presumably because it’s seen as too powerful and therefore too spammy and error-prone. PeopleBooks also points out that the function has been deprecated, and advises you to use the second option described below. However, if the requirement is to deliver a one-off, quick-and-dirty email message, ‘SendMail’ will still do the job with a minimum of fuss. The following is an example of sending a very basic email via ‘SendMail’:

Local String &mail_flags = 0;
Local String &mail_to = "emailaddress@test.com";
Local String &mail_cc = "";
Local String &mail_bcc = "";
Local String &mail_subject = "Test Message";
Local String &mail_text = "Body of the email message appears here";
Local String &mail_files = "";
Local String &mail_titles = "";

Local number &return_cd = SendMail(&mail_flags, &mail_to, &mail_cc,
                          &mail_bcc, &mail_subject, &mail_text,
                          &mail_files, &mail_titles);
   
If &return_cd <> 0 Then
   /* Email could not be sent */
Else
   /* Email successfully sent */
End-If;

Here’s a slightly more elaborate example of ‘SendMail’ that uses a file attachment (be sure to include a file name that actually exists on your system):

Local String &mail_flags = 0;
Local String &mail_to = "emailaddress@test.com";
Local String &mail_cc = "";
Local String &mail_bcc = "";
Local String &mail_subject = "Test Message";
Local String &mail_text = "Body of the email message appears here";
Local String &mail_files = "/tmp/sample_file.tst";
Local String &mail_titles = "sample_file.tst";

Local number &return_cd = SendMail(&mail_flags, &mail_to, &mail_cc,
                          &mail_bcc, &mail_subject, &mail_text,
                          &mail_files, &mail_titles);
   
If &return_cd <> 0 Then
   /* Email could not be sent */
Else
   /* Email successfully sent */
End-If;

The ‘return code’ value is very straightforward – either a 0 for success, or a -1 for failure.

C. App Package

The second and preferred approach is to use the ‘MCFOutboundEmail’ Application Class. Although this involves a bit more set-up than ‘SendMail’, the App Class contains a number of advanced features, such as specifying the format of the email (HTML or plain text), as well as giving you some better feedback if the email distribution happens to fail.

Firstly, here’s an example of using the App Class for sending a basic email (the code contains options for both HTML and plain text – just choose whichever is appropriate):

import PT_MCF_MAIL:MCFOutboundEmail;

Local PT_MCF_MAIL:MCFOutboundEmail &eMail;
&eMail = create PT_MCF_MAIL:MCFOutboundEmail();
   
/* Define mandatory fields */
&eMail.From = "my_email@server.com";
&eMail.Recipients = "person1@server.com, person2@server.com";
&eMail.CC = "person3@server.com";
&eMail.Subject = "Email Subject";

/* Define body of the email for plain text */
&eMail.Text = "This is a plain text message";
&eMail.ContentType = "text/plain";

/* Define body of the email for HTML */
&eMail.Text = "<html><body><H1><b>Welcome!</b></H1>" |
              "<p>Message in HTML format.</body></html>";
&eMail.ContentType = "text/html";

/* Define email attachment */
&eMail.AddAttachment("report.txt", %FilePath_Relative, "report.txt",
       "Error Report", "", "");

/* Send the email */
&result = &eMail.Send();

Evaluate &result
   When %ObEmail_Delivered
      &done = True;
      Break;
      
   When %ObEmail_NotDelivered
   When %ObEmail_PartiallyDelivered
   When %ObEmail_FailedBeforeSending
      &done = False;
      Break;
End-Evaluate;

If you wish to attach more than one file, as an alternative to using the email ‘AddAttachment’ method, you can create a ‘mult-part’ email consisting of both text and attachment files. Here is an example of a multi-part message:

import PT_MCF_MAIL:*;

Local PT_MCF_MAIL:MCFOutboundEmail &eMail;
&eMail = create PT_MCF_MAIL:MCFOutboundEmail();

/* Define mandatory fields */
&eMail.From = "my_email@server.com";
&eMail.Recipients = "person1@server.com, person2@server.com";
&eMail.CC = "person3@server.com";
&eMail.Subject = "Email Subject";

/* Create a body part for the email text */
Local PT_MCF_MAIL:MCFBodyPart &emailText;
&emailText = create PT_MCF_MAIL:MCFBodyPart();
&emailText.Text = "This email contains two attachments";

/* Create a body part for attachment 1 */
Local PT_MCF_MAIL:MCFBodyPart &attach1;
&attach1 = create PT_MCF_MAIL:MCFBodyPart();
&attach1.SetAttachmentContent("test.jpg", %FilePath_Relative,
         "test.jpg", "Test Image", "", "");

/* Create a body part for attachment 2 */
Local PT_MCF_MAIL:MCFBodyPart &attach2;
&attach2 = create PT_MCF_MAIL:MCFBodyPart();
&attach2.SetAttachmentContent(GetEnv("PS_SERVDIR") |
         "/test.csv", %FilePath_Absolute, "test.csv",
         "Test CSV", "", "");   

/* Attach the body parts to the main email message */
Local PT_MCF_MAIL:MCFMultipart &mp;
&mp = create PT_MCF_MAIL:MCFMultipart();
&mp.AddBodyPart(&emailText);
&mp.AddBodyPart(&attach1);
&mp.AddBodyPart(&attach2);
&eMail.MultiPart = &mp;

/* Send the email */
&result = &eMail.Send();

<< Previous | Next >>