Building Applications for SMTP and IMAP Storage¶

This chapter provides information about building applications to access storage devices that support Simple Mail Transfer Protocol (SMTP) and Internet Message Access Protocol (IMAP) interfaces.

XTML SMTP and IMAP PACs¶

This section defines the unique tabs included in the Properties window and the standard results available for each PAC listed under Mail on the Actions tab in the workspace pane.

These PACs allow applications to send and read messages from IMAP servers. SMTP is used for sending messages and IMAP is used for reading messages and manipulating mailboxes.

To use these PACs, the application server must be configured to start the ps_mail_agent process to establish persistent SMTP and IMAP connections to a specified server at startup. For more information, see the Application Server User’s Guide.

The Send Mail PAC sends mail only to the configured SMTP server. To send messages to other servers, the SMTP server must be configured to relay SMTP messages.

The remaining PACs use IMAP, and the specific IMAP server they operate on depends on the value of the user name. If the user name provided is a fully qualified domain name, the application server establishes an IMAP connection with the specified server. If the user name does not include a domain name, the application server sends the IMAP request to the statically-configured IMAP server specified in the application server configuration.

For more information about the common Description tab and Custom tab, see Build Functions and Custom Results.

Create Mailbox¶

The Create Mailbox PAC uses IMAP to create a mailbox under a specified user account. The user account must already exist on the specified IMAP server.

Properties¶

The Create Mailbox PAC includes the General tab.

General¶

*General Fields*¶
Field Name	Type	Description
Username	String	Name of the user account on the IMAP server under which the mailbox will be created. The account must exist on the IMAP server before executing this PAC.
Password	String	Configured password on the IMAP server for this account. Only required if the user name does not include a domain name and the request is therefore not being sent to the statically-configured IMAP server.
Mailbox	String	Name of the mailbox to be created.
Return Value	Integer	Value returned to the calling function to indicate the outcome of the operation. `0` - success `1` - login failed `2` - request failed `3` - unable to connect to server
Timeout	Short, Integer, Float	The time, in seconds, to wait for a response before timing out and returning a timeout error branch.

Exit Paths¶

In addition to the default result exit path, the Create Mailbox PAC includes the result exit paths listed in the following table.

Exit Path	Description
Success	Points to the next PAC to be executed in the event that the connection is successful.
Error	Points to the next PAC to be executed in the event that the operation returned an error.
Timeout	Points to the next PAC to be executed in the event that the operation times out.

Delete Mailbox¶

The Delete Mailbox PAC uses IMAP to delete a mailbox under a specified user account. The user account must already exist on the specified IMAP server.

Properties¶

The Delete Mailbox PAC includes the General tab.

General¶

*General Fields*¶
Field Name	Type	Description
Username	String	Name of the user account on the IMAP server under which the mailbox will be deleted. The account must exist on the IMAP server before executing this PAC.
Password	String	Configured password on the IMAP server for this account. Only required if the user name does not include a domain name and the request is therefore not being sent to the statically-configured IMAP server.
Mailbox	String	Name of the mailbox to be deleted.
Return Value	Integer	Value returned to the calling function to indicate the outcome of the operation. `0` - success `1` - login failed `2` - request failed `3` - unable to connect to server
Timeout	Short, Integer, Float	The time, in seconds, to wait for a response before timing out and returning a timeout error branch.

Exit Paths¶

In addition to the default result exit path, the Delete Mailbox PAC includes the result exit paths listed in the following table.

Exit Path	Description
Success	Points to the next PAC to be executed in the event that the connection is successful.
Error	Points to the next PAC to be executed in the event that the operation returned an error.
Timeout	Points to the next PAC to be executed in the event that the operation times out.

Get Mailbox Status¶

The Get Mailbox Status PAC returns the number of messages waiting in each category of a specified mailbox and the identifiers for those messages.

The application uses the message identifiers, which are integer values, to receive the messages with the Read Mail PAC. Message information is categorized as either urgent, unseen, or saved.

Properties¶

The Get Mailbox Status PAC includes the General tab.

General¶

*General Fields*¶
Field Name	Type	Description
Username	String	Name of the user account on the IMAP server from which the mailbox status is retrieved. The account must exist on the IMAP server before executing this PAC.
Password	String	Configured password on the IMAP server for this account. Only required if the user name does not include a domain name and the request is therefore not being sent to the statically-configured IMAP server.
Mailbox	String	Name of the mailbox for which status is retrieved. If not provided, the “INBOX” mailbox is checked.
Urgent count	Integer	Number of urgent messages.
Unseen count	Integer	Number of unseen messages.
Saved count	Integer	Number of saved messages.
Urgent identifiers	Object	Array of integers that identify a message that is marked urgent.
Unseen identifiers	Object	Array of integers that identify a message that is marked unseen.
Saved identifiers	Object	Array of integers that identify a message that is marked saved.
Return Value	Integer	Value returned to the calling function to indicate the outcome of the operation. `0` - success `1` - login failed `2` - request failed `3` - unable to connect to server
Timeout	Short, Integer, float	The time, in seconds, to wait for a response before timing out and returning a timeout error branch.

Exit Paths¶

In addition to the default result exit path, the Get Mailbox Status PAC includes the result exit paths listed in the following table.

Exit Path	Description
Success	Points to the next PAC to be executed in the event that the connection is successful.
Error	Points to the next PAC to be executed in the event that the operation returned an error.
Timeout	Points to the next PAC to be executed in the event that the operation times out.

Read Mail¶

The Read Mail PAC is used to read a message and associated attachments from an IMAP server.

To read a message, the unique message identifier must be known. Attachments are saved to local storage on the Application Server, and the filename is returned via an output variable in the PAC. The application server automatically removes the local files when the session ends, requiring no action from the application.

Properties¶

The Read Mail PAC includes the General tab.

General¶

*General Fields*¶
Field Name	Type	Description
Username	String	Name of the user account on the IMAP server that has the mailbox from which the email message will be read. The account must exist on the IMAP server before executing this PAC.
Password	String	Configured password on the IMAP server for this account. Only required if the user name does not include a domain name and the request is therefore not being sent to the statically-configured IMAP server.
Mailbox	String	Name of the mailbox from which the email message is being read. If not provided, the “INBOX” mailbox is checked.
Message ID	String	The identifier of the email message to be read.
From	String	The From header of this email message.
CC	String	The CC header of this email message.
To	String	The To header of this email message.
Date	String	The Date header of this email message.
Subject	String	The Subject header of this email message.
Body	String	The body, or main message, of this email message.
File 1-3	String	The email message can have up to 3 attached files.
Return Value	Integer	Value returned to the calling function to indicate the outcome of the operation. `0` - success `1` - login failed `2` - request failed `3` - unable to connect to server
Timeout	Short, Integer, Float	The time, in seconds, to wait for a response before timing out and returning a timeout error branch.

Exit Paths¶

In addition to the default result exit path, the Read Mail PAC includes the result exit paths listed in the following table.

Exit Path	Description
Success	Points to the next PAC to be executed in the event that the connection is successful.
Error	Points to the next PAC to be executed in the event that the operation returned an error.
Timeout	Points to the next PAC to be executed in the event that the operation times out.

Search Mailbox¶

The Search Mailbox PAC allows an application to perform a generic IMAP query against a specified mailbox to return the message identifiers that match the query. The returned message identifiers can then be used in other PACs to read or delete messages.

Properties¶

The Search Mailbox PAC includes the General tab.

General¶

*General Fields*¶
Field Name	Type	Description
Username	String	Name of the user account on the IMAP server that has the mailbox to search. The account must exist on the IMAP server before executing this PAC.
Password	String	Configured password on the IMAP server for this account. Only required if the user name does not include a domain name and the request is therefore not being sent to the statically-configured IMAP server.
Mailbox	String	Name of the mailbox to perform a generic IMAP query against. If not provided, the “INBOX” mailbox is checked.
Query		Generic IMAP query that indicates what to search for and match against in the specified mailbox.
Message IDs	Integer	Message identifiers of the messages that matched the query.
Return Value	Integer	Value returned to the calling function to indicate the outcome of the operation. `0` - success `1` - login failed `2` - request failed `3` - unable to connect to server
Timeout	Short, Integer, Float	The time, in seconds, to wait for a response before timing out and returning a timeout error branch.

Exit Paths¶

In addition to the default result exit path, the Search Mailbox PAC includes the result exit paths listed in the following table.

Exit Path	Description
Success	Points to the next PAC to be executed in the event that the connection is successful.
Error	Points to the next PAC to be executed in the event that the operation returned an error.
Timeout	Points to the next PAC to be executed in the event that the operation times out.

Send Mail¶

The Send Mail PAC sends mail by formatting and sending an SMTP request to the server that the application server establishes SMTP connections with.

That server must be configured for SMTP relay to enable delivery of messages to remote mail servers.

Properties¶

The Send Mail PAC includes the General tab.

General¶

*General Fields*¶
Field Name	Type	Description
From	String	The From header of this email message.
CC	String	The CC header of this email message.
To	String	The To header of this email message.
BCC	String	The BCC header of this email message.
Date	String	The Date header of this email message.
Subject	String	The Subject header of this email message.
Body	String	The body, or main message, of this email message.
Urgent	Checkbox	If selected, this email message will be marked as urgent.
File 1-3	String	The email message can have up to 3 attached files.
Return Value	Integer	Value returned to the calling function to indicate the outcome of the operation. `0` - success `1` - login failed `2` - request failed `3` - unable to connect to server
Timeout	Short, Integer, Float	The time, in seconds, to wait for a response before timing out and returning a timeout error branch.
Response code	String	Variable that holds the response code at the completion of the PAC.
Response text	String	Variable that holds the response text at the completion of the PAC.

Exit Paths¶

In addition to the default result exit path, the Send Mail PAC includes the result exit paths listed in the following table.

Exit Path	Description
Success	Points to the next PAC to be executed in the event that the connection is successful.
Error	Points to the next PAC to be executed in the event that the operation returned an error.
Timeout	Points to the next PAC to be executed in the event that the operation times out.

Update Mail¶

The Update Mail PAC allows an application to modify an existing message from an IMAP server by deleting it or marking it as urgent.

Properties¶

The Update Mail PAC includes the General tab.

General¶

*General Fields*¶
Field Name	Type	Description
Username	String	Name of the user account on the IMAP server that has the mailbox from which the email message will be updated. The account must exist on the IMAP server before executing this PAC.
Password	String	Configured password on the IMAP server for this account. Only required if the user name does not include a domain name and the request is therefore not being sent to the statically-configured IMAP server.
Mailbox	String	Name of the mailbox from which the email message is being updated.
Message ID	String	The identifier of the email message to be updated.
Operation	Drop-down List	Determines whether the message is to be deleted or marked marked as urgent.
Return Value	Integer	Value returned to the calling function to indicate the outcome of the operation. `0` - success `1` - login failed `2` - request failed `3` - unable to connect to server
Timeout	Short, Integer, Float	The time, in seconds, to wait for a response before timing out and returning a timeout error branch.

Exit Paths¶

In addition to the default result exit path, the Update Mail PAC includes the result exit paths listed in the following table.

Exit Path	Description
Success	Points to the next PAC to be executed in the event that the connection is successful.
Error	Points to the next PAC to be executed in the event that the operation returned an error.
Timeout	Points to the next PAC to be executed in the event that the operation times out.

Application Development Guidelines¶

The following are guidelines to follow when developing applications:

Configure the ps_master_config.xml file to start the ps_mail_agent process to implement the SMTP and IMAP interfaces. In the process section of the configuration file, you must specify the SMTP and IMAP servers to connect with. The ps_master_config.xml file should have a section similar to the following:

<ps-mail-agent temp-dir="C:\\company_app_server\\apps\\media\\local">
        <smtp server="mail.company.com" />
</ps-mail-agent>

Reading from IMAP storage is a two-step process. First, call the Get Mailbox Status PAC for a list of IMAP message identifiers. Second, call the Read Mail PAC for each message identifier to retrieve the message.
The Get Mailbox Status PAC returns information about each message category in the specified mailbox. Messages that are urgent have been marked as urgent by the sender and have not been read. Messages that are unseen have not been read. Messages that are saved have been read.
For each message category, the Get Mailbox Status PAC requires the int variable, which is the count of messages in the defined category, and the object variable, which is an array of integer values representing a message identifier for each message in the defined category.
The Read Mail PAC retrieves a single message from a mailbox. The message identifier obtained from a previous call to the Get Mailbox Status or Search Mailbox PACs is required. You provide the IMAP user name and message identifier (mailbox name is optional and INBOX will be used by default if none is provided) to retrieve, as output parameters, message information including the message body and SMTP header fields.
The Read Mail PAC also retrieve attachments. Attachments are placed in local file storage on the application server and stored with a temporary file name that is returned to the application. The file is automatically deleted by the application server when the application session ends. An application plays .wav file attachments using the Play and Collect PAC.