8 Parlay X 2.1 Multimedia Messaging/SMTP, POP3, and IMAP

This chapter describes the Parlay X 2.1 Multimedia Messaging/SMTP, POP3, and IMAP protocols in Oracle Communications Services Gatekeeper.

Overview of the Parlay X 2.1 Multimedia Messaging/SMTP, POP3, and IMAP Communication Service

The Parlay X 2.1 Multimedia Messaging/SMTP, POP3, and IMAP communication service exposes the Parlay X 2.1 Multimedia Messaging set of application interfaces.

The communication service acts as a Value Added Service (VAS) application connecting to an email server using the SMTP, POP3, and IMAP protocols. It provides the capability of applying policy such as throttling and black listing to manage and regulate the flow of email.

For the exact version of the standards that the communication service supports for the application-facing interfaces and the network protocols, see the appendix on standards and specifications in Concepts Guide.

Using this communication service, an application can:

• Send emails to one or more destination addresses. The attachments in these emails can be of any type that can be specified using MIME.

• Sign up to be notified that delivery receipts for sent emails have been delivered to the email server.

• Receive delivery receipts on sent or retrying emails.

• Explicitly query Services Gatekeeper for delivery receipts on sent emails.

• Sign up to be notified when specified emails for the application have been received from the email server.

• Receive notifications that specified emails for the application have been received from the email server. These notifications provide a message ID, but do not include the message payload.

• Explicitly poll Services Gatekeeper for emails sent to the application that have arrived from the email server and been stored in Services Gatekeeper.

Requests can flow in two directions. They can be application-initiated or network-triggered.

Processing Application-Initiated Requests

Application-initiated requests can be:

• Send Requests

• Send Receipts

• Delivery Receipts

• Retry Requests

Send Requests

When an application sends a request using Parlay X 2.1 Multimedia Messaging protocol to Services Gatekeeper, if the sender address and destination addresses start with the schema email:, Services Gatekeeper transforms the request to an email and uses SMTP protocol to send the request to an email server.

• Routing mechanism

  For this communication service, each plug-in instance connects to an email server by SMTP. Routing should be based on sender address but not destination address. In PluginManager MBean, when adding a route for the email plug-in instance, the value should use ^.* to match all addresses, for example, ^.*@oracle.com$. This means that the plug-in instance connects to oracle email server and all the requests with a sender address that matches the regular expression should be routed to this plug-in instance.

• SMTP connections management

  Each email plug-in instance creates an SMTP connection pool. The connections in the pool connect to SMTP server separately. Each connection can be in IDLE, BUSY, or DISCONNECT status and should send heartbeat to maintain itself. If disconnected, it should reconnect to SMTP server. When a plug-in instance receives a new request, it should select a connection in IDLE status from the pool, and set it to BUSY status. If the connection fails, enlarge the pool until it reaches the maximum connection number. If it still fails, the plug-in instance sends the request to the retry manager.

• Email subject, body and attachments

  When transforming the Parlay X 2.1 Multimedia Messaging request to an email message, set subject in email with the subject value in the original request. For email body and attachments, since there are only attachments in the original request, add an X-Parameter ContentInFirstAttachment to indicate whether there is an email body or not. If this X-Parameter is set to "true," or is absent, then the first attachment contains the email body and other attachments are handled as regular attachments. If this X-Parameter is set to "false," then all attachments are handled as regular attachments and the email body is blank.

• Multiple destination addresses

  For a request with multiple destination addresses, since Services Gatekeeper cannot use the common routing mechanism as mentioned above, the plug-in instance should be responsible for splitting single email into multiple emails and sending it to each address.

Send Receipts

For this communication service, send receipts are acknowledgements that Services Gatekeeper has received the request from the application by means. The result values in the send receipts are UUIDs (Universally Unique Identifiers) created by Services Gatekeeper used to correlate subsequent delivery receipts at a later time. Although a single email message may be sent to multiple destination addresses, only one send receipt is returned to the application. The receipt is returned synchronously in the response message to the sendMessage operation.

Delivery Receipts

Delivery receipts contain the final delivery status of the email message. They report whether the email message has actually been delivered to the delivery recipient by the network. There is one delivery receipt per destination address, with one of four possible outcomes:

• DeliveryUncertain (the initial status)

• DeliveredToNetwork

• MessageWaiting (retry status)

• DeliveryImpossible (message could not be delivered since the retry limit was exceeded)

Applications can either choose to have delivery receipts delivered to them automatically by supplying Services Gatekeeper with a callback interface or they can choose to poll Services Gatekeeper.

When Services Gatekeeper receives a request from an application, it creates an UUID and returns that UUID in the send receipts to application. It stores the delivery receipt for each destination address with initial status in temporary in-memory storage with the UUID and callback interface (if any).

After Services Gatekeeper sends an email successfully or fails to do so, it updates the delivery receipt in the in-memory store, if a callback interface exists, and sends the delivery receipt to notify the application.

If the application does not supply a callback interface, the application can poll Services Gatekeeper with the UUID for these stored delivery receipts.

DeliveredToNetwork and DeliveryImpossible are final delivery statuses. The stored delivery receipt should be removed if the status for all the destination addresses belonging to one UUID is a final status and are delivered to application callback interface or have been polled by application.

Each stored delivery receipt is time stamped. After a configurable time period, the stored delivery receipt is removed.

Retry Requests

When Services Gatekeeper sends an email which temporarily fails for any reason (such as no connection), it stores the request in storage, updates the status to MessageWaiting for this request, and sends a delivery receipt to the application (if a callback interface was provided).

After a configurable time interval, Services Gatekeeper retrieves the failed request from the store and attempts to resend the request. The number of retry attempts are also configurable.

If retry attempt for the send request succeeds, Services Gatekeeper updates the status to DeliveredToNetwork for this request and sends a delivery receipt.

If the number of retry attempts are exhausted and the send request has not succeeded, Services Gatekeeper updates the status to DeliveryImpossible for this request and creates a delivery receipt indicating the failure.

Processing Network-triggered Requests

For an application to receive emails from the network, it must indicate its interest in these messages by registering for online notification in Services Gatekeeper. A notification is defined by a service activation number, which is the destination address of the email. An application can use the following operations to register for online notification:

• ParlayX 2.1 StartMessageNotification. See Parlay X Web Services Part 5: Multimedia Messaging specification

• Use Operation: startMessageNotification to register for online notification from the Administration console.

An application can also register to receive email messages offline. Services Gatekeeper stores the messages and delivers them when the application requests them. Use Operation: enableReceiveEmail from the Administration console to provision offline notification of network-triggered email messages.

Extensions to ParlayX 2.1 interface include:

• X-Parameter "Password" to indicate the credential of the email service activation number. The value should be encrypted by AES (Advanced Encryption Standard) or 3DES (Triple Data Encryption Standard) algorithm.

• X-Parameter "SizeLimit" to indicate the maximum total size (in kilobyte) of an email message attachment accepted by Services Gatekeeper.

• Each registered notification must be unique, and notification attempts with overlapping service activation number are rejected.

When Services Gatekeeper receives an online/offline notification request, it starts a POP3 or IMAP process according to the configuration. When using POP3, Services Gatekeeper uses the polling mechanism and retrieves emails from email server using a configurable interval. When using IMAP, Services Gatekeeper attempts to utilize IDLE mechanism (whereby when new emails arrive it is notified by email server and retrieves the email). If the email server does not support the IDLE mechanism, then Services Gatekeeper falls back to the polling solution.

When using POP3 or IMAP3 protocols, Services Gatekeeper handles emails it receives in the following ways:

• The application has registered for online notification. Services Gatekeeper sends the message to the application, and the application receives the message and acknowledges receiving it.

  If the email only has pure text body without attachments, the text is included in the notification sent to the application.

  If the email message is not pure text, the notification sent to the application includes a reference to the attachments stored in storage. The application uses that reference to retrieve the attachments.

• Offline notification has been provisioned. Services Gatekeeper stores the email. The application retrieves the message as described in Retrieving Offline Messages.

Retrieving Offline Messages

A ParlayX application fetches newly-arrived email messages with the getReceivedMessages operation. The response from this method is an array of MessageReference objects, one for each newly-arrived email message.

If an email message is pure text, the text message is included in the MessageReference object. If an email message is not pure text, the MessageReference object includes the reference to the attachments. The application then uses the reference to retrieve the attachment using the getMessage operation. See the Parlay X Web Services Part 5: Multimedia Messaging specification for descriptions of this operation.

Application Interfaces

For information about the SOAP-based interface for the Parlay X 2.1 MultiMedia Messaging/MM7 communication service, see the discussion of Parlay X 2.1 Interfaces in Application Developer's Guide.

For information about the RESTful interface, see the discussion of Multimedia Messaging in RESTful Application Developer's Guide.

The RESTful Service interfaces provide RESTful access to the same functionality as the SOAP-based interfaces. The internal representations are identical, and for the purposes of creating SLAs, reading CDRs, and so on, they are the same

This communication service uses a plug-in which enables applications to send email using Simple Mail Transfer Protocol (SMTP) and receive email using Post Office Protocol (POP) version 3 and Internet Message Access Protocol (IMAP).

See Statement of Compliance for details on the SMTP, POP and IMAP interfaces supported.

Events and Statistics

The Parlay X 2.1 MultiMedia Messaging/SMTP, POP3, and IMAP communication service generates Event Data Records (EDRs), Charging Data Records (CDRs) and alarms to assist system administrators and developers in monitoring the service.

For general information, see Appendix A, "Events, Alarms, and Charging."

Event Data Records

Table 8-1 lists the IDs of the EDRs created by the Parlay X 2.1 MultiMedia Messaging/SMTP, POP3, and IMAP communication service. It does not include EDRs created when exceptions are thrown.

Table 8-1 Event Types Generated by Email Communication Service

EDR ID	Method Called
8107	SendMessage
8108	getMessageDeliveryStatus
8102	startMessageNotification
8103	stopMessageNotification
8104	getReceivedMessages
8106	getMessage
8110	notifyMessageDeliveryReceipt
8111	notifyMessageReception
8120	submit email to email server
8121	delivery receipt for email
8122	receive email from email server

Charging Data Records

MultiMedia Messaging/SMTP, POP3, and IMAP CDRs are generated under the following conditions:

• When an email has been sent from Services Gatekeeper to the email server

• When an email received from the email server.

Alarms

For the list of alarms, see Alarm Handling Guide.

Managing Parlay X 2.1 MultiMedia Messaging/SMTP, POP3, and IMAP

This section describes the properties and workflow for Parlay X 2.1 Multimedia Messaging/SMTP, POP3, and IMAP plug-in instances.

Properties for Parlay X 2.1 MultiMedia Messaging/SMTP, POP3, and IMAP

Table 8-2 lists the technical specifications for the communication service.

Table 8-2 Properties for MultiMedia Messaging/SMTP, POP3, and IMAP

Property	Description
Managed object in Administration Console	sendMessagedomain_name > OCSG > server_name > Communication Services > plug-in_instance_id
MBean	Domain=com.bea.wlcp.wlng Name=wlng_nt InstanceName=same as the network protocol instance_id assigned when the plug-in instance is created Type=oracle.ocsg.plugin.multimediamessaging.email.management.EmailManagementMBean
Network protocol plug-in service ID	Plugin_px21_multimedia_messaging_email
Network protocol plug-in instance ID	The ID is assigned when the plug-in instance is created. See the description for managing and configuring the Plug-in Manager in System Administrator's Guide.
Supported Address Scheme	email
Application-facing interfaces	com.bea.wlcp.wlng.px21.plugin.MessageNotificationManagerPlugin com.bea.wlcp.wlng.px21.plugin.ReceiveMessagePlugin com.bea.wlcp.wlng.px21.plugin.SendMessagePlugin com.bea.wlcp.wlng.px21.callback.MessageNotificationCallback
Service type	MultimediaMessaging-ParlayRestMms
Exposes to the service communication layer a java representation of:	Parlay X 2.1 Part 5: Multimedia Messaging
Protocols used for interfaces with the network nodes	SMTP, POP3, and SMTP
Deployment artifact: NT.EAR wlng_nt_multimedia_messaging_px21.ear	Plugin_px21_multimedia_messaging_mm7.jar Plugin_px21_multimedia_messaging_email.jar px21_multimedia_messaging_service.jar multimedia_messaging_mm7_rel5mm712.war multimedia_messaging_mm7_rel5mm715.war
Deployment artifact: AT EAR: Normal wlng_at_multimedia_messaging_px21.ear	px21_multimedia_messaging_callback.jar px21_multimedia_messaging.war rest_multimedia_messaging.war

Configuration Workflow for Parlay X 2.1 MultiMedia Messaging/SMTP, POP3, and IMAP

Use the following procedure to configure the plug-in instance using the Administration Console or an MBean browser:

1. Create one or more instances of the plug-in service. See the section on Managing and Configuring the Plug-in Manager in System Administrator's Guide.

   Use the plug-in service ID listed in Properties for Parlay X 2.1 MultiMedia Messaging/SMTP, POP3, and IMAP.

2. Select the MBean for the plug-in instance. The MBean display name is the same as the plug-in instance ID given when the plug-in instance was created.

3. Configure the behavior of the plug-in instance using attributes related to the SMTP/POP3/IMAP protocols according to email server information.

4. Set up the routing rules to the plug-in instance. See the section on Managing and Configuring the Plug-in Manager in System Administrator's Guide.

   Use the plug-in instance ID and address schemes listed in Properties for Parlay X 2.1 MultiMedia Messaging/SMTP, POP3, and IMAP.

5. If required, create and load a node SLA. For details see the section on Defining Global Node and Service Provider Group Node SLAs and Managing SLAs in the Accounts and SLAs Guide.

6. Provision the service provider accounts and application accounts.

Provisioning Workflow for Parlay X 2.1 MultiMedia Messaging/SMTP, POP3, and IMAP

The following steps outline the provisioning workflow for the communication service.

1. Use Operation: activeSmtpConfig to connect to email server by SMTP protocol after you configure or update SMTP-related attributes. Use Operation: listSmtpConnection to monitor the status of each connection in the connection pool.

2. Use Operation: enableReceiveEmail to register offline notifications. This specifies that received emails should not result in notifications to an application but should instead be stored in Services Gatekeeper for polling.

   Use the following operations to manage the offline registrations:

   • Operation: listOfflineNotificationInfo

   • Operation: getOfflineNotificationInfo

   • Operation: removeOfflineNotificationInfo

3. Use Operation: startMessageNotification to register online notifications. This is to manage registrations for received emails on behalf of an application.

   Use the following operations to manage the online registrations:

   • Operation: listOnlineNotificationInfo

   • Operation: getOnlineNotificationInfo

   • Operation: removeOnlineNotificationInfo

Reference: Attributes and Operations for Parlay X 2.1 MultiMedia Messaging/SMTP, POP3, and IMAP

This section describes the attributes and operations for configuration and maintenance:

• Attribute: smtpUserName

• Attribute: smtpPassWord

• Attribute: smtpHost

• Attribute: smtpPort

• Attribute: smtpAuth

• Attribute: smtpSSLRequired

• Attribute: smtpStartTLS

• Attribute: smtpRetryNumber

• Attribute: smtpRetryInterval

• Attribute: smtpInitConnectionNumber

• Attribute: smtpMaxConnectionNumber

• Attribute: smtpReconnectInterval

• Attribute: smtpNoopInterval

• Attribute: receiveProtocol

• Attribute: pop3Host

• Attribute: pop3Port

• Attribute: pop3SSLRequired

• Attribute: pop3PollingInterval

• Attribute: imapHost

• Attribute: imapPort

• Attribute: imapSSLRequired

• Attribute: imapPollingInterval

• Attribute: debug

• "Operation: activeImapConfig"

• Operation: activeSmtpConfig

• Operation: enableReceiveEmail

• Operation: listImapProcess

• Operation: listPop3Process

• Operation: listSmtpConnection

• Operation: startMessageNotification

• Operation: getOfflineNotificationInfo

• Operation: getOnlineNotificationInfo

• Operation: listOfflineNotificationInfo

• Operation: listOnlineNotificationInfo

• Operation: removeOfflineNotificationInfo

• Operation: removeOnlineNotificationInfo

Attribute: smtpUserName

Scope: Cluster

Unit: Not applicable

Format: String

Specifies the user name for the SMTP server.

Attribute: smtpPassWord

Scope: Cluster

Unit: Not applicable

Format: String

Specifies the password for the SMTP server.

Attribute: smtpHost

Scope: Cluster

Unit: Not applicable

Format: String

Specifies the address for the SMTP server.

Attribute: smtpPort

Scope: Cluster

Unit: Not applicable

Format: String

Specifies the port for the SMTP server.

Attribute: smtpAuth

Scope: Cluster

Unit: Not applicable

Format: Boolean

Specifies if the SMTP server needs authentication.

Set to true to use authentication, otherwise false.

Attribute: smtpSSLRequired

Scope: Cluster

Unit: Not applicable

Format: Boolean

Specifies if the SMTP server requires SSL.

Set to true to require SSL, otherwise false.

Attribute: smtpStartTLS

Scope: Cluster

Unit: Not applicable

Format: Boolean

Specifies if the SMTP server requires TLS.

Set to true to require TLS, otherwise false.

Attribute: smtpRetryNumber

Scope: Cluster

Unit: Not applicable

Format: Integer

Specifies number of retries.

Enter the number of retries. Default is 3.

Attribute: smtpRetryInterval

Scope: Cluster

Unit: Seconds

Format: Integer

Specifies the number of seconds between the retries for a request.

Enter the number of seconds. Default is 300.

Attribute: smtpInitConnectionNumber

Scope: Cluster

Unit: Not applicable

Format: Integer

Specifies the SMTP initial connection number.

Enter the initial connection number. Default is 1.

Attribute: smtpMaxConnectionNumber

Scope: Cluster

Unit: Not applicable

Format: Integer

Specifies the maximum number of SMTP connections.

Enter the maximum connection number. Default is 16.

Attribute: smtpReconnectInterval

Scope: Cluster

Unit: Seconds

Format: Integer

Specifies the number of seconds between the reconnection attempts.

Enter the number of seconds. Default is 60.

Attribute: smtpNoopInterval

Scope: Cluster

Unit: Seconds

Format: Integer

Specifies the number of seconds in the heartbeat interval.

Enter the number of seconds. Default is 300.

Attribute: smtpSizeLimit

Scope: Cluster

Unit: Not applicable

Format: Integer

Specifies the number of seconds in the heartbeat interval.

Enter the number of seconds. Default is 300.

Attribute: receiveProtocol

Scope: Cluster

Unit: Not applicable

Format: String

Specifies the protocol used to receive email.

Enter POP3 or IMAP. Default is IMAP.

Attribute: pop3Host

Scope: Cluster

Unit: Not applicable

Format: String

Specifies the address to the POP3 Server.

Attribute: pop3Port

Scope: Cluster

Unit: Not applicable

Format: String

Specifies the port for the POP3 Server.

Attribute: pop3SSLRequired

Scope: Cluster

Unit: Not applicable

Format: Boolean

Specifies if the POP3 server requires SSL.

Set to true to require SSL, otherwise false.

Attribute: pop3PollingInterval

Scope: Cluster

Unit: Seconds

Format: Integer

Specifies the number of seconds in the polling interval for POP3 server.

Enter the number of seconds. Default is 120.

Attribute: imapHost

Scope: Cluster

Unit: Not applicable

Format: String

Specifies the address to the IMAP Server.

Attribute: imapPort

Scope: Cluster

Unit: Not applicable

Format: String

Specifies the port for the IMAP Server.

Attribute: imapSSLRequired

Scope: Cluster

Unit: Not applicable

Format: Boolean

Specifies if the IMAP server requires SSL.

Set to true to require SSL, otherwise false.

Attribute: imapPollingInterval

Scope: Cluster

Unit: Seconds

Format: Integer

Specifies the number of seconds in the polling interval for IMAP server.

Enter the number of seconds. Default is 120.

Attribute: debug

Scope: Cluster

Unit: Not applicable

Format: Boolean

Specifies whether to print debug information for SMTP/IMAP/POP3.

Set to true to require the debug information, otherwise false.

Operation: activeImapConfig

Scope: Local

Makes the modification to IMAP take effect.

Signature:

activeImapConfig()

Operation: activeSmtpConfig

Scope: Local

Makes the modification to SMTP-related attributes take effect. This method should be invoked after the following attributes are modified:

• smtpUserName

• smtpPassWord

• smtpHost

• smtpPort

• smtpAuth

• smtpSSLRequired

• smtpStartTLS

Signature:

activeSMTPConfig()

Operation: enableReceiveEmail

Scope: Cluster

Adds an offline notification for applications that poll for email messages. Email messages matching the short code will not result in a callback to an application. Instead, the message is stored in Services Gatekeeper. This method returns the correlator uniquely identifying the new notification. The application has to use the correlator returned by this method to poll for email messages.

Signature:

enableReceiveEmail(shortcode: String, password: String, criteria: String, appInstGroupID: String, sizeLimit int)

Table 8-3 enableReceiveEmail Parameters

Parameter	Description
shortcode	Destination address or the activation for the email account start with email:, for example, email: [e-mail]
password	The credential for the email account indicated by the shortcode.
criteria	The text to match against to identify the application which is to receive the notification. (Not used in this service)
appInstGroupID	The application instance group ID associated with this notification
sizeLimit	The maximum kilobytes of total size of all attachments application can accept.

Operation: listImapProcess

Scope: Local

Lists the IMAP processes running in this server

Signature:

listImapProcess()

Operation: listPop3Process

Scope: Local

Lists the POP3 processes running in this server

Signature:

listPop3Process()

Operation: listSmtpConnection

Scope: Local

Lists the status of the SMTP connections in this server

Signature:

listSmtpConnections()

Operation: startMessageNotification

Scope: Cluster

Adds an online notification for applications that for some reason cannot (or are not allowed) call the startMessageNotification method. Returns the correlator uniquely identifying the new notification.

Signature:

startMessageNotification(shortcode: String, password: String, criteria: String, appInstGroupID: String, sizeLimit int)

Table 8-4 startMessageNotification Parameters

Parameter	Description
endpoint	End point for the notification.
shortcode	Destination address or the activation for the email account starting with email:, for example, email:[e-mail]
password	The credential for the email account indicated by the shortcode.
criteria	The text to match against to identify the application which is to receive the notification. Not used in this service.
appInstGroupID	The application instance group ID associated with this notification
sizeLimit	The maximum kilobytes of total size of all attachments application can accept.

Operation: getOfflineNotificationInfo

Scope: Cluster

Retrieves the notification associated with the specified correlator returned by Operation: enableReceiveEmail.

Signature:

getOfflineNotification(Correlator: String)

Operation: getOnlineNotificationInfo

Scope: Cluster

Retrieves the notification associated with the specified correlator returned by Operation: startMessageNotification and the online notification started through an application interface.

Signature:

getOnlineNotification(Correlator: String)

Operation: listOfflineNotificationInfo

Scope: Cluster

Displays a list of all notifications registered offline by Operation: enableReceiveEmail.

Signature:

listOfflineNotificationInfo()

Operation: listOnlineNotificationInfo

Scope: Cluster

Displays a list of all notifications registered by Operation: startMessageNotification.

Signature:

listOnlineNotificationInfo()

Operation: removeOfflineNotificationInfo

Scope: Cluster

Removes a notification registered offline using Operation: enableReceiveEmail.

Signature:

removeOfflineNotificationInfo(Registration Identifier: String)

Table 8-5 removeOfflineNotificationInfo Parameters

Parameter	Description
Registration Identifier	ID of the notification.

Operation: removeOnlineNotificationInfo

Scope: Cluster

Removes a notification registered by an application or on behalf of an application by Operation: startMessageNotification.

Signature:

removeOnlineNotificationInfo(Registration Identifier: String)

Table 8-6 removeOnlineNotificationInfo Parameters

Parameter	Description
Correlator	ID of the notification.