Retrieving Email From a Mail Server With the MCFGetMail Class

Use the MCFGetMail class to retrieve email from your mail server and load it in a rowset. After you have decided that an email needs to be saved to the PeopleSoft database, use MCFMailStore class.

The following list describes the different levels of the rowset that contains email information, and what each level contains.

Field or Control

Definition

Level 0

The first row at level zero is empty except for the number of rows contained within level zero and return status. The first row contains the return status for the entire batch of emails. Apart from the return status of the whole batch, each individual row has its own EMAIL_RET_STATUS. When a fatal error occurs, such as a connector size overflow, an IB overflow, or an error accessing attachments , the return status is copied to the first row. Subtle errors like unsupported encoding for a part of a individual email appear in the return status of that email only. Each row after the first row contains information about an individual email, such as the header information, the time received, and so on.

Level 1

Level one is where the parts of an email reside. The level one child rowsets are linked to the parent rowset in level zero by the MCF_EMAIL_ID, a unique ID assigned by PeopleSoft.

Note: Multipurpose Internet Mail Extensions (MIME) is an Internet standard for representing multipart and multimedia data in email. It enables email to be exchanged between different email systems. The parts may be nested. PeopleSoft embeds the JavaMail API to implement support for the MIME standard. However, all parts of an email are represented in PeopleSoft as level one rowsets, regardless of the hierarchy that existed in the original email.

The following table describes the fields within the rowset at level zero.

Field

Description

MCF_ATTACH_LIST

Contains a list of all the file names that are attachments for a particular email.

Multiple items are separated by a semicolon (;).

MCF_IS_ATT_URL

This is a Boolean value indicating whether the email body is located in the MCF_EMAIL_TEXT or in the attachment directory.

If this value is 1 (true), the email body is located in the attachment directory and can be accessed using the MCF_ATT_URL value.

If this value is 0 (false), then the email body is located in MCF_EMAIL_TEXT.

MCF_ATT_URL

This URL enables you to view an attachment. This URL is viewable only if the corresponding email has been authorized for the current user.

This value is a relative URL. The URL becomes fully qualified only after the rowset has been saved to the PeopleSoft database and then later retrieved using the MCFMailStore class.

The following is a sample URL: http://sundance.example.com/PSAttachServlet/ps/mcfdev1/39297_31030554591_1.gif?contentType=image/gif

mcfdev1 is the mail user name.

39297__31030554591_1.gif is the file name in the attachment directory.

contentType is used by the browser to open a viewer associated with this type.

The filename of the downloaded attachment is constructed by using the email's unique ID and the part number.

Warning! Downloading the same emails twice from the mail server overwrites the associated files in the directory. If the same email is stored twice in the PeopleSoft database, the system creates two separate rows. If you delete either one of these rows, the system deletes the associated files in the directory. To avoid this situation, delete emails from the mail server after you have retrieved them.

See AuthorizeEmailAttach.

MCF_IBNODE_NAME

Identifies the name of the Integration Broker node that received the email, such as MCF_GetMail.

The system uses this value to construct the fully qualified URL required for viewing attachments.

MCF_ATTACH_SIZES

Indicates the size of the attachments associated with an email.

Multiple values are separated by a semicolon (;).

The attachment sizes appear in the same order as the file names in MCF_ATTACH_LIST.

MCF_EMAIL_FROM

Indicates the email account that sent the email, such as jsmith@example.com.

MCF_DTTM_RECV

Indicates the time that the mail server received the email.

Warning! If you are using a Post Office Protocol 3 (POP3) mail server, this field may not be populated.

MCF_OFFSET_RECV

Indicates the time zone of the mail server that received this email.

Note: This field contains the time zone of the integration gateway used to fetch this email.

MCF_DTTM_SENT

Indicates the time that the email was sent.

MCF_OFFSET_SENT

Indicates the time zone of the mail server that sent this email.

Note: Currently, this field contains the time zone of the integration gateway used to fetch this email.

MCF_DTTM_SAVED

Records the date and time that the PeopleSoft system saved an email to the PeopleSoft database.

If you use a POP3 mail server, PeopleSoft recommends using this value as the base, or starting point, for any time-sensitive transactions.

MCF_EMAIL_SENDER

This is the reply to address. This supports a mail feature in which users can send an email from one account, but when the receiver chooses to reply, the system addresses the email to a different account. For instance, sales representatives may send an email from their personal email account, as in tom_sawyer@example.com, but when customers reply, the email is addressed to sales@example.com.

MCF_EMAIL_TEXT

Represents the text that was delivered in the body of the email.

Before the email is downloaded, this field contains the body of the email. After the email has been downloaded, this field is blank.

Check the MCF_IS_ATT_URL value to determine whether your email text resides in this field or the attachment directory.

PeopleSoft relies on the originating email client embedding encoding information to determine character set. For example, Content-type: text/plain; charset=Big5

MCF_NOTIFY_CC

Indicates the parties who were copied (carbon copied) on the email. Multiple addresses are separated by a semicolon (;).

MCF_NOTIFY_TO

Indicates the parties who received the email. Multiple addresses are separated by a semicolon (;).

MCF_UID_LIST

This contains a unique identifier created by POP3 or an IMAP4 mail server. It is guaranteed to be unique within a particular mail box.

Note: The DeleteEmail method also uses this value when deleting a list of emails. When deleting emails, this field can contain multiple values separated by a space.

MCF_WL_SUBJECT

Contains the subject of the email. A maximum of 254 characters is allowed.

PeopleSoft relies on the originating email client embedding encoding information to determine character set.

For example:

Email Subject:  Subject: =?Big5?B?uvuqwLBPqsy67qZYs/i+yS+kpLDqqXik6Ldztdg=?= =?Big5?B?uvSlSKTOpEilwbr0MzCk6bVvqu2q+KTloUGkaqRP?==?Big5?B?scCxUqa/v0GlwQ==?=  

where ?Big5? is the prefixed encoding information.

MCF_RET_STATUS

Represents where the system stores the return status of a particular mail class method.

MCF_EMAIL_STATUS

This field is not currently used.

MCF_NUMROWS

Indicates the number of rows (level one child rowsets) that contain parts of a particular email. For example, if an email has two child rowsets associated with it at level one, this value would be 2.

Note: For row one of the level zero rowset, this field reflects the number of emails in this rowset. If you fetch 10 emails, the rowset contains 11 rows, but the MCF_NUMROWS value in row 1 equals 10. Row 1 of the level zero rowset never contains an email.

MCF_EMAIL_MSG_ID

This is the globally unique identifier for this email. This ID is generated by the mail server that sent this email.

MCF_REPY_TO

This is the reply to field.

MCF_REF_IDS

Use this field for the reference header fields of the message.

MCF_REPLY_IDS

This value contains the email address that the email can reply to.

MCF_MSG_SIZE

Represents the total size of the entire email. This value includes the sizes of attachments.

MCF_EMAIL_LANG_CD

This value reflects the language code of the Integration Broker node that received this email.

Note: PeopleSoft recommends setting up email accounts that are dedicated to one language such as, support_french@example.com and support_english@example.com. This enables you to anticipate the language of the email you read into your system. In turn, configure separate Integration Broker nodes to handle each of the languages you support. There are no language recognition procedures within the PeopleSoft system.

MCF_USER

Represents the user account (mail box) on the mail server that received the email.

MCF_SERVER

Represents the mail server that received the email.

MCF_ERROR_COUNT

Used to return the number of messages that caused errors during processing on the target connector.

MCF_QUARANTINE_COUNT

Used to return the number of messages that caused errors during processing on the target connector and were successfully moved to the quarantine folder (This value is always 0 for POP3).

MCF_CONTENT_TYPE

This is the content type of the email itself. For example, a content type could be text/plain, text/html, or multipart/alternative.

MCF_EMAIL_HEADERS

This field is used to return the email message headers. It contains the raw headers in RFC 822 format. The MCFHeaders class can be used to parse the contents of this field.

The following table describes the fields within the rowset at level one. This rowset contains the parts of the email.

Field

Description

MCF_ATT_URL

This is the URL of an associated attachment in the attachment directory.

This URL is a relative value when this rowset is first received from the mail server and stored in the database. It only becomes a fully qualified URL once you retrieve the rowset using the MCFMailStore class.

Keeping the URL a relative value enables you to make changes within the system without breaking the URL.

MCF_IS_ATT_URL

This is a Boolean value indicating whether the email part is located in the MCF_EMAIL_TEXT or on the attachment directory.

If this value is 1 (true), the email part can be accessed using the MCF_ATT_URL value.

If this value is 0 (false), then the email part is located in MCF_EMAIL_TEXT.

MCF_FILENAME

Represents the file name for an attachment, such as revenue.xls or resume.doc. The file name can be used as a read-only label on the page used by end users to view attachments. For example, the file name may appear next to the link that opens the attachment.

Note: Not all parts have file names.

MCF_FILE_DATA

This field is not currently used.

MCF_EMAIL_HEADERS

This field is used to return the email part headers. It contains the raw headers in RFC 822 format. The MCFHeaders class can be used to parse the contents of this field.

MCF_EMAIL_TEXT

Contains the text content of the email part.

Note: Although the same rowset structure is used for retrieving email from the mail server and for retrieving email from the PeopleSoft database, not all of the fields apply to each situation. For example, when you first retrieve email from the mail server, the rowset does not contain the fully qualified URL to any attachments.

Note: After an email is saved to the database, always use the methods in the MailStore application package class to access the email. Do not read directly from the mail tables.

The GetMail Integration Broker connector returns message codes denoting status. These return codes apply to all the methods within the MCFGetMail class. The following are returned in MCF_RET_STATUS field, and by the Status property.

Field or Control

Definition

0

Success.

1

Connector size overflow.

The size of the email requested exceeds the value in MCF_EmSz_Conn.

The system returns the header information for this email with the return status set to 1.

See Configuring GETMAILTARGET Connector Properties.

2

Integration Broker threshold size overflow.

The size of the email requested exceeds the value in MCF_EmSz_IB.

This happens when the size of the XML message constructed to transfer emails from the mail server to the database exceeds the threshold value.

If there are any more emails to be processed in the current batch, the system does not fetch them from the mail server. For example, suppose your program fetches 20 emails at a time from the mail server, and this error occurred on the tenth email. In this case, the system processes the tenth email, but emails 11–20 are still be on the mail server.

See Configuring GETMAILTARGET Connector Properties.

3

Cannot delete all the messages from the mail server.

4

Connecting to the mail server failed.

5

The attachments to be deleted were not found.

6

At least one attachment cannot be deleted.

7

Unsupported encoding.

8

Cannot write to the attachment directory.

9

Messages were downloaded to directory and deleted from mail server.

This status code occurs when an exception occurs in Integration Broker while storing the emails to the database. The exception might occur due to invalid characters in the email. If the email is left on the mail server, the same exception will occur repeatedly, preventing you from fetching further emails. Because the header might contain these invalid characters also, only MCF_RET_STATUS, MCF_MSG_SIZE, MCF_UID_LIST, date time fields, MCF_IS_ATT_URL, MCF_ATT_URL are set. There is no way to determine which email caused the exception, so the system writes all the emails to the directory. All the emails in the batch are deleted from the mail server.

Field or Control

Definition

10

Email content error. One example of this is unsupported encoding.

Field or Control

Definition

11

Returned if attempting to create a mail server folder while using the POP3 protocol.

12

Folder creation on mail server failed.

13

GetMail connector internal error.

See Status.