Interfacing with Email

This release of PicLan-IP supports a programming interface allowing you to format and send internet email messages using SMTP (Simple Mail Transfer Protocol). SMTP is the standard internet protocol for sending email.

This documentation is designed for PicLan-IP build 2.0.0(129)

In order to use email functions, you will need to have the following elements in place:

Your Pick host must have PicLan-IP installed and running.
You must have a supervisor process and at least one thread process running.
You must have at least one DNS configured and accessible.
You must have PicLan-IP SMTP send-mail functions enabled in your PicLan-IP license.

How Mail is Sent

Internet email can be sent in one of two ways:

If your ISP has an email server, you can send email to that server and it will forward it to the destination address.
You can send the email directly to the destination address (or to one of the destinations backup relays).

The advantage of using your ISP's email server is that it will take care of email retries without your system needing to worry about it. The advantage of sending the mail directly is that you do not rely on your ISP's mail server. To understand the importance of this decision, a quick discussion of internet mail routing is appropriate here:

Internet Email Routing and Retries

When email is sent over the internet, it may or may not be directly sent to the recipient's mail server. Part of the Domain Name Server's function is to support a system of mail forwarding information called Mail eXchange (MX) records. These pieces of data tell mail users and mail servers how to deliver an email message to a particular destination. Simple destination may have a single MX entry that is just the machine name of the mail server at the destination. More complicated examples may have several systems listed, any of which can accept inbound internet email, or backup system that can store and forward the message if the primary mail server is down or unreachable.

When email is sent over the internet, there is no expectation that the mail can be sent instantaniously. In fact, the standard requires that a mail server try to deliver a message for five days before giving up on it. If you setup your Pick system to directly send mail to a destination mailbox and not use your ISP's mail server, then your Pick system has the responsibility of trying to send a message for five days. If the Pick host is a production system that is always running, this is probably fine. If the Pick host is a part-time host, then using your ISP's mail server is better because it becomes another system's responsibility to retry failed mail messages.

Email Internals

The email database files in PicLan-IP include cross-reference files that are mainained using high-performance BTREE indexes. These indexes are nearly impossible to manually query or maintain, so you must be sure to use the doucmented interfaces whenever updating any of the mail database files.

Email Subroutine Documentation

Sending an Email Message

The process of sending a message is a multi-step process:

Formatting the message
Sending the message
Sending multiple messages
Checking on the status of the sent message

First the message must be formatted correctly so that it looks like an internet email message and then this message must be transmitted to the destination.

Formatting an Email Message

The process of formatting an email message involves building the header fields that the message requires followed by including the message body. In general, email message can have three general levels of complexity:

Simple Messages - the message body contains printable text only
Encoded Messages - the message body contains encoded text (perhaps binary data)
Multi-part Messages - the message body contains multiple parts, some of which may be encoded.

The first version of the PicLan-IP email support only include support for simple messages. Support for encoding and multi-part MIME (Multimedia Internet Mail Extensions) messages will be included in a future build.

You have two choices in formatting a message. Your application program can build the message itself as a text string using attribute marks to delimit lines, or you can use a helper subroutine within PicLan-IP to add internet header fields onto you message body.

If you use the helper function, you application will call the subroutine:

DIM CONTENTS(100)
...
PLM.BUILD.MSG(PARMS,MAT CONTENTS,MSG,FR.ADDR,TO.ADDR,R.ERR)

This subroutine will take the contents of PARMS and CONTENTS and return MSG, FR.ADDR, TO.ADDR, and R.ERR. The PARMS and CONTENTS parameters are designed to support multi-part and encoded messages, even though these functions are not working in the build.

PARMS Parameter

The PARMS paramter is a dynamic array that you build prior to calling PLM.BUILD.MSG. This dynamic array has the following format:

PARMS<1>: The email address that the message is from in "sloppy" internet format. This allows you to include descriptive narative with the email address such as "Doug Dumitru" doug@modsoft.com or Doug Dumitru <doug@modsoft.com>

PARMS<2>: The email address(es) that you wish the message to be delivered to. You can specify multiple addresses seperated by commas. Again these addresses are in "sloppy" internet format.
PARMS<3>: Carbon Copy (CC) address(es) that you wish the message to be copied to. You can specify multiple addresses seperated by commas. Again, these address are in "sloppy" internet format.
PARMS<4>: Blind Carbon Copy (BCC) address(es) that you wish the message to be copied to. Internet email messages do not include a header field for BCC addresses, so an original recipient will not know that you also sent the message to a BCC.
PARMS<5>: Message subject.
PARMS<6>: Reply to address. If included this "sloppy" internet format address will be included in a "Reply-To:" header. A reply to header is where email clients will send replys (unless the user overrides this address).
PARMS<7>: To: string. If included, this string will be included in the "To:" header. If not included, then the to address list will be included in the "To:" header field. This field is usually used for mailing lists where you do not wish to list all of the recipients of the message in the header.
PARMS<8>: CC: string. If included, this string will be included in the "CC:" header. If not included, then the CC address list will be included in the "CC:" header field.
PARMS<21 ...>: If you included text in attributes 21 or greater, then this text will be appended to the message header without interpretation. This allows you to add customized header fields. If you specify a header field in attributes 21 or greater that is one of the standard header fields that PLM.BUILD.MSG usually creates, then you user-supplied header field will take precidence.

CONTENTS Array Parameter

The CONTENTS parameter is a dimensioned array with 100 elements. The reason this field is supplied as a dimensioned array is to support multi-part messages. With this build of PicLan-IP, you should set all elements of this array to null except the first element.

CONTENTS(1)<1>: A string that indicates where the message body is stored. Possible values are:
CONTENTS(1)<2>: The encoding of the message with character set. Supported values are:
CONTENTS(1)<3>: How the message is to be stored in the mail message. Supported values are:
CONTENTS(1)<10 ...>: The actual text content of the message if INLINE is specified.

The PARMS variable and CONTENTS array are the only two values that you need to specify when calling PLM.BUILD.MSG. The following paramters are returned from the subroutine call and are used in subsequent calls to actually sent the email:

Result Parameters

MSG: This parameter will contain the text contents of the message including the message header and body.
FR.ADDR: This is the internet address that the message is from with extraneous words removed.
TO.ADDR: These are the addresses where the message will be sent with extraneous words removed. The TO.ADDR entries include To:, CC:, and BCC: addresses. Multiple addresses are stored as multiple attributes within this parameter.
R.ERR: This field should normally be set to null upon return from PLM.BUILD.MSG. If this field is non-null, it indicates that and error was encountered in building the email message and that the message cannot be sent.

Sending the Message

After the message has been formatted, either manually or using the PLM.BUILD.MSG subroutine, you need to schedule the message to be transmitted. The term "schedule" is used here because the mail message may or may not be sent immediately. To schedule a message for transmission, you call the subroutine:

PLM.SEND(FR.ADDR,TO.ADDR,MSG,ID,R.ERR)

The FR.ADDR, TO.ADDR, and MSG fields are the results of the PLM.BUILD.MSG subroutine.

The ID is a string returned that identifies the message so that you can subsequently check on it's status.

The R.ERR is a string returned that indicates any error condition that prevents the message from being scheduled. Even if the error string is null, the message will not necessarily be delivered if it has invalid addresses or if network connections or mail hosts are down.

Sending a Batch of Messages

If you are building a large quantity of messages to send, the PLM.BUILD.MSG and PLM.SEND functions are not ideal. First, they are not really optimized for performance, and second, because they are very "black-box" in nature, they have to run a lot of internal initialization code on every call. If you are sending a large number of messages you may wish to use an alternate interface.

PLM-SEND-BATCH file

This TCP command will take an input data file along with an active select list and generate one email message for each item in the specified data file. The format of these items is:

001 FR.ADDR
002 TO.ADDR (multi-valued if multiple addresses are specified)
003 MSG

Checking the Status of a Message

This function is not currently implemented.