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 IMailbox interfaceIGXMailBox 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( )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( )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( )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( )RetrieveReset( ). This method undeletes and unmarks any messages that were affected by the previous rRetrieve( ) call.

To receive email

3. Create an instance of IGXMailbox by calling createMailbox( )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);

   IMailbox mb;

   mb = createMailbox("mail.myOrg.com","myUserName",

      "pass7878","sid@blm.org");

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

   hr = pMBox->Open(OPEN_RECV);

   result = mb.open(GX_MBOX_OPEN_FLAG.OPEN_RECV);

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

   LONG res;

   res = pMbox->RetrieveCount();

   int mbCount = mb.retrieveCount();

6. To retrieve messages, instantiate an IGXValList object to contain the email messages, then call retrieve( )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);

   IValList messages = GX.CreateValList();

   messages = mb.retrieve(true, false);

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

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

8. hr = pMbox->RetrieveReset(); result = mb.retrieveReset();

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

   pMBox->Close();

   mb.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();

// Create mailbox object to connect to a POP mail server

IMailbox recvMB;

public void recvMail()

{

   // Only check messages received after the last open

   BOOL Latest = true;

   // Remove retrieved messages from the mail server

   BOOL Delete = true;

   // Create an IMailbox instance

   IMailbox recvMB;

   recvMB = createMailbox(recvhost, user, pswd, useraddr);

   if (recvMB != null)

   {

      if (recvMB.open(GX_MBOX_OPEN_FLAG.OPEN_RECV))

      {

         // Count the number of new messages

         int numMsgs = recvMB.retrieveCount();

         if(numMsgs > 0)

         {

            IValList mesgList;

            // Retrieve the new messages

            mesgList = recvMB.retrieve(Latest,Delete);

            // Use IValList methods to iterate through

            // the returned IValList. The keys in the

            // IValList are the message numbers. The

            // values are the email messages as strings

         }

         recvMB.close();

      }

   }

}

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( )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 sSend( ) 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( )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);

   IMailbox mb;

   mb = createMailbox("mail.myOrg.com","myUserName",

      "pass7878","sid@blm.org");

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

   hr = pMBox->Open(OPEN_SEND);

   int result = mb.open(GX_MBOX_OPEN_FLAG.OPEN_SEND);

3. To send the message, call send( )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"); java.lang.String[] ppTo = {"sal@dat.com","sid@blm.com",null};

   int mbSend = mb.send(ppTo,"Testing email");

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

   pMBox->Close();

   mb.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();// Define the string parameters that will be passed

// to IMailbox methods

String sendhost = "smtp.kivasoft.com";

String recvhost = "pop.kivasoft.com";

String user = "eugene";

String pswd = "eugenesSecretPassword";

String useraddr = "eugene@kivasoft.com";

String sendTo[] = {"friend@otherhost.net", null};

String mesg = "Hi Friend, How are you?";

public void sendMail()

{

   // Create an IMailbox instance

   IMailbox sendMB;

   sendMB = createMailbox(sendhost, user, pswd, useraddr);

   if (sendMB != null) // sendMB successfully created

   {

      // Open a session with the mail server

      if (sendMB.open(GX_MBOX_OPEN_FLAG.OPEN_SEND))

      {

         // Send a mail message

         sendMB.send(sendTo,mesg);

         // Close the mailbox session

         sendMB.close();

      }

   }

}