Email Response Processor

The Email Response Processor is a utility designed to handle both bounced email messages and returned email messages from users asked to reply by email or those who want to unsubscribe from mailing lists. You can use it to automatically handle the contents of any POP3 mailbox.

This chapter contains the following sections:

• Understanding the Email Response Processor

• Email Response Processor Configuration Files

• Script Reference

• Email Response Processor Performance Issues

Understanding the Email Response Processor

The Email Response Processor consists of a combination of mail process threads. Each thread processes a set of mailboxes as instructed by a mail script. Two types of threads are included, categorized by the types of mailboxes they process:

• Reply Process

• Bounce Process

The following rules apply in general to the Email Response Processor:

• Each type of mailbox has its own instance of a mail process thread and its own configuration file.

• Each mail process thread runs on separate threads generated by the Email Response Processor.

• Each mail process thread has a separate configuration file. The scripts that handle the behavior of each mail process thread are included in the thread’s individual configuration file.

• The number of mail process threads generated is determined by the number of configuration files passed to the Email Response Processor.

• The mail process thread handles mailboxes in a round-robin fashion. The threads operate concurrently. Because their operation depends on a number of factors (such as the number of emails in the mailbox, the type of operation performed on each email, and so forth), the order of their operation cannot be predetermined.

The advantage to this design is that mailboxes can be categorized and assigned to different mail process threads, thus improving performance. Each set of mailboxes is treated differently using separate configuration and mail script files. No hardcoded limit exists to the number of mail process threads that can be created—the limit is dependent only on the number of configuration files passed to the Email Response Processor.

How the Email Response Processor Works

The Email Response Processor’s two components, the Reply Process and the Bounce Process, work similarly, each controlled by its own script. The Reply Process or Bounce Process begins by contacting the POP3 server. It opens the first mailbox in its list, reads the messages one at a time, and executes its script once for each message. When the specified number of emails have been processed in the first mailbox (as determined by the maxMailToGetPerPOPSession parameter), that mailbox closes and the Email Response Processor moves on to the next mailbox.

After it has completed processing on all the specified mailboxes, the Email Response Processor stops immediately and waits a specified amount of time before beginning again. If it reaches the limit set in the maxMessagesPerHour configuration parameter, it will stop immediately and wait until the end of the current hour before continuing to the next mailbox. By doing this, the Email Response Processor ensures that it will not use all the available resources and will not overlook a mailbox because another is too active (and thus consuming too many resources).

Note. The Email Response Processor never deletes an email message unless the script specifically instructs it to do so. By default, the Reply Process’s configuration file deletes messages that contain body text such as “Auto Reply,” “automated response,” and similar, and the Bounce Process’s configuration file deletes all bounced messages after they have been processed. Refer to the appropriate configuration file (ReplyProcess.script or BounceProcess.script) for a complete list of such text.

Understanding Email Bounces

When an email message “bounces,” it means that the mail server has rejected the message. There are many reasons for this, including:

• The message is too large.

• The recipient's inbox is full.

• Something in the message's content triggered a spam filter.

• The recipient's address isn't valid.

In any case, for whatever reason the email message is rejected, the Email Response Processor must log these bounces so that the administrator can determine whether emails were delivered, and if not, why.

There are three types of bounces: hard, soft, and unknown.

• A hard bounce is a message that is permanently undeliverable due to an invalid recipient address or because the recipient's mail server is blocking your server.

  Another name for hard bouncing is “Permanent Failure.”

• A soft bounce occurs if the mail server recognizes the address but cannot deliver the message. This might be because the recipient's inbox is full, the server is down, the connection is broken, or the user has abandoned the mailbox. Emails can also soft-bounce if the sender's mail server doesn't understand why the receiving mail server refused the message. Soft bounces can be temporary problems—for example, the connection breaks during the relay, too many messages swamp the server, or something similar. Most mail servers will retry soft-bouncing messages, but the messages aren't guaranteed to be delivered.

  Another name for soft bouncing is “Persistent Transient Failure.”

• An unknown bounce is a message for which the Email Response Processor cannot determine a reason for the bounce.

Running Email Response Processor

You start and stop Email Response Processor through the Maintain Dialog Servers page in the Online Marketing Control Center.

See Maintaining Dialog Servers.

Email Response Processor Configuration Files

The Email Response Processor uses a configuration file named ERP.config to specify the database connectivity information. This file is installed during Email Response Processor installation. Refer to your installation documentation for further information about this file.

The Email Response Processor’s functionality is configured in two files: ReplyProcess.script and BounceProcess.script. The configuration files are similar and are divided into two parts:

• A parameter section, defining global parameters

• A rules section, describing the way incoming emails should be handled

Additionally, an optional error handling section defines the actions to execute if an error occurs during normal operation.

Parameter Section

The parameter section of the configuration files allows for the global configuration of the Email Response Processor (SMTP mail servers and mailboxes). Each parameter is defined in this manner:

name = value [, value...] ;

The following table shows the parameters:

Example

The following example shows the parameters section of a configuration file with some of the values set.

popServer	= [email protected] ;
popUsers	= (ps, 12345) ;
smtpServers	= [email protected] ;
logFile	= Reply_Processor.log ;

See Also

PeopleSoft Enterprise CRM 9 Supplemental Installation Guide

Setting Up PeopleSoft Online Marketing

Rules Section

The rules section of the configuration file contains a simple script that describes what the Email Response Processor should do with the emails it receives. The script, executed for each message in each of the mailboxes, is a list of actions to be performed in sequence.

You can control which parts of the script are executed for each email using the following structure:

if <condition> then <action> [else <action>] end

The action can be either a single action (such as delete or forward) or a list of action enclosed in curly braces. To provide greater control, you can nest these blocks.

The condition that triggers an action is most commonly the presence of a particular character string in a particular part of the message. For example, if the email contains the string “unsubscribe” then the script might direct the Email Response Processor to forward the email to an address set up to handle unsubscribe requests. You can combine conditions using the AND and OR keywords or negate them with the not keyword.

Note. Only the Reply Process checks conditions on received emails. The Bounce Process assumes that the popUsers parameter contains only mailboxes designated as bounce mailboxes and that these mailboxes contain only bounced email messages. For more information about setting up bounce mailboxes, refer to Using PeopleSoft Online Marketing.

Example

The following example shows the rules section of a Reply Process configuration file. In this example, if the string “Original Message” appears in the message body, the email is forwarded to the email address [email protected]. If the string “unsubscribe” appears in the message body, the email is forwarded to [email protected]. Afterward, the email is deleted from the mailbox (including any emails not containing the specified strings in the body).

...
if inBody ("Original Message") then
	forward ([email protected]) ;
else {
		if inBody ("unsubscribe") then {
			forward ([email protected]) ;
	}
}
delete;
...

Note. Be aware that if you use multiple mailboxes for processing replies, all the mail is not necessarily processed at the same time. For example, if you have four mailboxes set up to process unsubscribe requests and reply with confirmation notices, some notices might be delivered sooner than others depending on which mailbox received the request.

Error Handling Section

When an error occurs in the main script, the execution is interrupted, the error is logged, and then the section is executed.

The error handling section of the configuration file is introduced by the onError keyword:

onError <action>

for example:

onError delete

Example

The following section shows the error handling section of a configuration file. In this case, messages generating errors are deleted.

Note. Comments are preceded by “//”.

...
onError			/ /ensure that the message is deleted
	delete;

Script Reference

The following section provides a reference to the scripting language used in the Email Response Processor configuration file.

Note. The complete sample ReplyProcess.script and BounceProcess.script scripts, which you can modify to suit your needs, are located in <PeopleTools_install_dir>/JavaApps/CRM/OMK/ERPx, where x is the identifier of each Email Response Processor instance created.

Conditions

This section describes the conditions you can specify in the ReplyProcess.script configuration file. In each case, the proper syntax for the condition is included, along with an example of its use.

Note. Only the Reply Process checks conditions on received emails. The Bounce Process assumes that the popUsers parameter contains only mailboxes designated as bounce mailboxes and that these mailboxes contain only bounced email messages.

inSender

The inSender condition looks for the specified string within the From field of the email.

The inSender syntax is as follows:

inSender ([boolean ignoreCase] "String")

For example:

inSender ("[email protected]")

inRecipient

The inRecipient condition looks for the specified string within the To field of the email.

The inRecipient syntax is as follows:

inRecipient ([boolean ignoreCase] "String")

For example:

inRecipient ("[email protected]")

inSubject

The inSubject condition looks for the specified string within the Subject field of the email.

The inSubject syntax is as follows:

inSubject ([boolean ignoreCase] "String")

For example:

inSubject ("Returned Mail")

inBody

The inBody condition looks for the specified string within the body of the email.

The inBody syntax is as follows:

inBody ([boolean ignoreCase] "String")

For example:

inBody ("unsubscribe")

inHeader

The inHeader condition looks for the specified string within the header of the email.

The inHeader syntax is as follows:

inHeader ([boolean ignoreCase] "String")

For example:

inHeader ("Reply-Processor")

inAll

The inAll condition looks for the specified string within the body or the header of the email.

The inAll syntax is as follows:

inAll ([boolean ignoreCase] "String")

For example:

inAll ("unsubscribe")

contactNotFound

The contactNotFound condition is true if the sender of the message cannot be identified.

The Email Response Processor tries to determine contact information from the magic number if it is present. If no magic number is found and the parameter getContactFromSender is set to on, the email address is used instead. If both methods fail, the contact is considered to be unidentified.

Note. The Email Response Processor uses only the main addresses, not the alternative email address, to determine contact information.

The contactNotFound syntax is as follows:

if
	contactNotFound
		then 
			{
			<action>;
			}

For example:

if 
	inRecipient("abuse")
then 
		if
			contactNotFound
		then	
			{
			forward("[email protected]");
			delete;
			}     

boolean IgnoreCase

In each condition described previously, the boolean IgnoreCase element is optional. If set to false, the matching is case-sensitive; otherwise, case is ignored. The default value is true.

For example:

inSender (false, "[email protected]")

would find “[email protected]” but not “[email protected]”.

Checking for Multiple Conditions

You can use all of the string checking conditions to check for the occurrence of any or all of several strings in the same command. To do this, insert all or any before the condition and provide a comma-separated list of strings for which to search. For example:

all inBody (true, "String 1", "String 2")

checks if “String1” and “String2” are in the body of the message, using a case-insensitive match. Substituting any results in a check for either of the two conditions.

Note. This type of checking is more efficient in both speed and memory usage than combining multiple individual conditions with the AND or OR keywords.

Actions

This section describes the syntax for actions performed upon the email message if the specified conditions are met.

delete

Deletes the message from the mailbox. Note that although the message is removed from the POP server, the remainder of the script is still executed for the message.

If the message is not deleted, it will remain on the server. This means that the next time the Email Response Processor is run, it will perform the specified actions on the message again.

Note. Be sure to test your Email Response Processor configuration carefully to ensure that only those messages you intend to delete are removed.

forward (address)

Forwards the message to the address specified.

To enable the Email Response Processor to forward mail to another domain, you might have to include that domain in the relay control of the SMTP mail server. (For example, if your domain is xyz.com and you are forwarding mail to [email protected], you must add demo.com to the relay control of your SMTP mail server(s).)

Note. If the Email Response Processor is forwarding email to a mailbox with business rules associated with it (for example, Kana), be sure to test thoroughly to ensure that mail is properly processed.

reply (string file)

Replies with the contents of the specified file. The original message is quoted after the included text.

ignore

Ignores the message. The action is still logged, unlike those messages that do not fit any of the rules.

Note. All preceding actions in the script are executed, but all following actions are ignored.

Database Actions

This section describes the syntax for actions performed upon the database if the specified conditions are met.

update (field, value)

Updates the specified profile field with the specified value. The fieldname must be in table.column format, and the value is the proper value for the field. The syntax differs depending on whether a basic profile field or a custom profile field is updated.

Basic Profile Field Update:

The format for field is BASIC.XXXX, where XXXX is a valid basic profile field name (exactly as it appears in the PeopleSoft Online Marketing Client, including spacing and case). The value should be a valid value for the field type. No SQL format is allowed.

Example:

update ("BASIC.Do Not Email", "Y");

If the Basic profile field type is Multiple Choice, the format is:

update("fieldname", "<semicolon separated code list>");

For example,

update("BASIC.MultiChoice1", "code1;code3;code6");

If the field type is Date, the date format is 'YYYY-MM-DD'; for example:

update("BASIC.Birth Date", "1968-02-03" );

If the field type is Time, the format is "HH:mm" in 24 hour format. For example:

update("BASIC.Time 1", "14:25" );

The system checks to see if the basic profile field name is supported. If it is not supported, the systems reports an error at initialization.

Custom Profile Field Update:

For a custom profile field, the following format is used:

update (field, value)

The field name must be in table.column format, where table is a valid custom profile table. The value must be in proper SQL format.

For example:

SQL Server:

update (APP_YOUR_CUSTOM_TABLE.YOUR_COLUMN, "value")
update (APP_YOUR_CUSTOM_TABLE.ROW_LASTMANT_DTTM, "getdate()" );

Oracle:

update (APP_YOUR_CUSTOM_TABLE.YOUR_COLUMN, "value")
update (APP_YOUR_CUSTOM_TABLE.ROW_LASTMANT_DTTM, "sysdate" );

DB2:

update (APP_YOUR_CUSTOM_TABLE.YOUR_COLUMN, "value");
update (APP_YOUR_CUSTOM_TABLE.ROW_LASTMANT_DTTM, "current_timestamp");

It is recommended that you also update the ROW_LASTMANT_DTTM column along with the column and value you wish to change, as this will enable other applications or database extracts to capture changes made by the Email Response Processor.

logSoftBounce

Logs in the database that the current email bounce is a soft bounce.

logHardBounce

Logs in the database that the current email bounce is a hard bounce.

You can configure the system to set the DO_NOT_EMAIL flag for recipients of hard bounces. This configuration parameter is set on the Global Options page.

See Setting Global Options.

logUnknownBounce

Logs in the database that the current email bounce is an unknown bounce (that is, the system cannot determine if the bounce is hard or soft).

logBounce

Logs in the database that an email message has been bounced against a specified contact. The contact is identified from the magic number (or from the Sender field if the magic number is not present and the getContactFromSender parameter is set to true). If the contact cannot be obtained, the corresponding information is logged in the logfile.

Note. This is a legacy action from pre-8.95 versions of Online Marketing. It will log the bounce as an unknown bounce type.

Error Handling

You can define an error-handling block for an operation or group of operations by enclosing the operation between the keywords try and onError. For several operations, enclose the operations between curly braces.

For example, the following statement attempts to update the Do Not Email field of the BASIC profile. If the operation fails, the message is forwarded to another email address.

try
	update ("BASIC.Do Not Email", "‘Y’");
onError
	forward ([email protected]);

Email Response Processor Performance Issues

In order to maintain a high level of performance, the same mailbox should not be passed to more than one mail process thread. Special care should be taken in the following cases:

• The same POP3 user should not be included in more than one configuration file. This is because after a thread has logged in to a POP3 mailbox, the next thread cannot log in to the same POP3 mailbox until the first thread has logged out. This can affect the system’s performance.

• The same configuration file should not be passed to the Email Response Processor more than once. This could result in more than one thread using the same log file, or in more than one thread attempting to process the same POP3 mailbox.

An error message will display and the Email Response Processor will stop running if you attempt to pass the same configuration filename more than once or if you have the same mailbox name in more than one file.

Updating the DO_NOT_EMAIL flag for hard bounces can affect performance.

Email Response Processor Script Language Keywords

The following keywords are used by the Email Response Processor:

• all

• and

• any

• contactNotFound

• delete

• else

• end

• forward

• if

• ignore

• inAll

• inBody

• inHeader

• inRecipient

• inSender

• inSubject

• logBounce

• logHardBounce

• logSoftBounce

• logUnknownBounce

• not

• onError

• or

• reply

• then

• try

• update