Chapter 10   Integrating Applications with Email


This chapter describes how to write applications that both send and receive electronic mail (email).

The following topics are included in this chapter:

• Introduction to Email in iPlanet Application Server Applications

• Receiving Email

• Sending Email

Introduction to Email in iPlanet Application Server Applications

---

The iPlanet Application Server Foundation Class Library supports email through the IGXMailBox interface.

In order for email applications to work, you must have access to one or both of the following types of email servers:

• SMTP server if you want to send email. Not required if you only want to receive email.

• POP server if you want to receive email. Not required if you only want to send email.

Security in Email

Security is often a concern when sending or receiving email. If the application generates and sends email using user input to set the address or content, then there is a risk of propagating inappropriate messages or mailing to incorrect recipients. Be sure to validate all user input before incorporating it in email.

Receiving Email

---

To receive email, your application must have access to a POP server.

Before retrieving messages, you can use RetrieveCount( ) to see how many messages are waiting in the specified inbox on the mail server. By checking first, you can avoid attempting to retrieve messages if the mailbox is empty. You can also use this technique when you need to know how many messages are waiting in order to construct a loop that will iterate through them one by one.

To retrieve messages, call Retrieve( ). Depending on the parameters you pass to this method, you can customize the retrieval process in the following ways:

• Retrieve all messages

• Retrieve only unread messages

• Delete messages from the mail server as they are retrieved

Only those messages received before the last call to Open( ) will be retrieved. You can not open a mailbox session, leave it open, and continuously receive emails. Instead, you must open a new session each time you want to retrieve new email.

After retrieving messages, you can return the mailbox to its original state by calling RetrieveReset( ). This method undeletes and unmarks any messages that were affected by the previous Retrieve( ) call.

To receive email

3. Create an instance of IGXMailbox by calling CreateMailbox( ). In this call, you specify valid user information and the name of the POP server you want to access. For example:

   hr = pMMBox->CreateMailbox("smtp", NULL, NULL,

      "sid@blm.com", (IGXObject **)&pMbox);

4. Open a session on your POP server by calling Open( ) with the OPEN_RECV flag. For example:

   hr = pMBox->Open(OPEN_RECV);

5. To find out whether you have messages, call RetrieveCount( ). For example:

   LONG res;

   res = pMbox->RetrieveCount();

6. To retrieve messages, instantiate an IGXValList object to contain the email messages, then call Retrieve( ). For example, the following code retrieves the latest unread messages and does not delete them from the mailbox:

   IGXValList *msgs = NULL;

   hr = pMbox->Retrieve(TRUE, FALSE, &msgs);

   Only the messages received before the call to Open( ) are retrieved.

7. To undo changes, call RetrieveReset( ). For example:

8. hr = pMbox->RetrieveReset();

9. To close the session, call Close( ). For example:

   pMBox->Close();

You can have only one mail server session open at a time. For example, suppose you open a session with the OPEN_RECV flag, then want to send email. You must first close the existing session, then open another one with the OPEN_SEND flag.

Example
The following code retrieves email:

LONG res;

pMMbox->CreateMailbox("smtp","sdas","sdas",

   NULL, (IGXObject **)&pMbox);

pMbox->Open(OPEN_RECV);

if ((res=pMbox->RetrieveCount()) > 0) {

   IGXValList *msgs = NULL;

   printf("Mailbox has %d messages\n", res);

   hr = pMbox->Retrieve(FALSE, FALSE, &msgs);

   CHAR msgno[16];

   msgs->ResetPosition();

   while (msgs->GetNextKey(msgno, 16) == NOERROR) {

      GXVAL val;

      hr = msgs->GetValByRef(msgno, &val);

      printf(Msg %s:\"%s"\n", msgno, val.u.pstrVal);

   }

   msgs->Release();

pMbox->Close();

pMbox->Release();

Sending Email

---

To send email, your application must have access to an SMTP server. Construct the email address and message separately, then use the Send( ) method to send the email out through the server.

You can send email to a single recipient or to a group of recipients. To send email to a group, use one of the following techniques:

• Pass the email addresses to Send( ) as an array.

• Use a loop to send a series of messages one at a time.

You can populate an address array dynamically using the results of a query, in which each row returned by the query is one email address. Use a loop to iterate through the rows in the query's result set and assign the data to successive elements of the array.

For example, this multiple-recipient technique would be useful for sending email to all customers to notify them of changes on your Web site.

To send email

1. Create an instance of IGXMailbox by calling CreateMailbox( ). In this call, you specify valid user information and the name of the POP server you want to access. For example:

   hr = pMMBox->CreateMailbox("smtp", NULL, NULL,

      "sid@blm.com", (IGXObject **)&pMbox);

2. Open a session on your SMTP server by calling Open( ) with the OPEN_SEND flag. For example:

   hr = pMBox->Open(OPEN_SEND);

3. To send the message, call Send( ). Pass a single email address or an array of addresses to this method, along with the text of the message. For example:

4. pMbox->Send(ppTo, "Testing, please ignore");

5. To close the session, call Close( ). For example:

   pMBox->Close();

   You can have only one mail server session open at a time. For example, suppose you open a session with the OPEN_SEND flag, then want to retrieve your email. You must first close the existing session, then open another one with the OPEN_RECV flag.

Example
The following code sends email:

LONG res;

LPSTR ppTo[2];

pMMbox->CreateMailbox("smtp","sdas","sdas",

   NULL, (IGXObject **)&pMbox);

pMbox->Open(OPEN_SEND);

ppTo[0] = "sdas@kello.com";

ppTo[1] = NULL;

pMbox->Send(ppTo, "Testing, please ignore");

pMbox->Close();

pMbox->Release();