Whitebeam e-mail control through SmtpRequest class.

Site Map
Application Guide
  Quick Start
  PHP and ASP
  Writing Apps
    Postgres Interface
    XML Processing
    Using XPath
    Binary Object
    Using HttpRequest
    Meta Data
    Memb Services
    Page Look&feel
    Message Groups
    Form Handling
Contact Whitebeam
Whitebeam Users

Whitebeam e-mail control through SmtpRequest class.


The SmtpRequest JavaScript class has been introduced with version 0.9.21 of the Presentation Engine. The class is fairly simple to use and is similar to the existing HttpRequest class. The class provides complete control of email generation including the ability to create multipart emails (for example to include attachments or to include a rich text HTML variant of an email).

The class encapsulates and abstracts the standard interface to an SMTP server. The formal class specification is available as the SmtpRequest JavaScript class.

Previous version of the Whitebeam system have included basic access to email via the Message Template. The advantages of this new mechanism include:

  • Unlimited message size.
  • Ability to control the SMTP headers, including the Content-Type, allowing generation of rich text 'newsletter' emails.
  • Support for 'multipart/*' content type allowing the creation of emails with attachements.

SmtpRequest fields in more detail

The SmtpRequest is controlled by the properties the client sets on the object before invoking the 'send' method. The properties on the object are described as follows:

msg.toArrayOne of theese *must* exist and be non-empty. Each address is a string object containing the target email address.
msg.ccArrayContents of the 'CC' header *and* added to the RCPT TO: if envTo not set.
msg.bccArrayAdded to the RCPT TO: if envTo not set, otherwise ignored.
rawDataBooleanIf this property is present and has the value of 'true' then the client script is going to generate the entire data section of the email message ( i.e. everything apart from the envelope data). In this case the data section of the message is taken from the 'defaultText' property, which in this case is mandatory
defaultTextStringUsed in two different ways:
  1. If the message is a multi-part encoding then this property is inserted into the message before the start of the first part.
  2. If the 'rawData' flag is set then this property contains the ENTIRE MESSAGE (but not the envelope).

In all other cases this property is ignored.

msg.multipartStringIf the mime type is calculated to be multipart/something this this property is checked and will contain the something part. The default if not present is mixed. This property is only used if the 'body' property is an array with more than one entry.
subjectStringSubject: header. Ignored if rawData is 'true'
replyToStringReply-To: header. Ignored if rawData is 'true'
fromStringFrom: header. Also used as the 'MAIL FROM:' envelope header *if* there is no 'sender' property. Ignored if rawData is 'true'.
senderStringIf present then this is put into the 'MAIL FROM:' envelope header and overrides the 'from' value.
headersObjectEach property in the object is a string. The name of the property is the name of a header and the string value is the header value. Although you can set things like the 'Sender:' header through this property - it is overridden if you set the specific property (eg msg.sender overrides msg.headers.sender).
bodyObject *or* ArrayUsed to generate the body of the message *if* the rawData flag is false or not present. See below for details.

The 'msg.body' parameter provides the body of the email message provided the 'rawData' flag is absent or set to false. The object may be either:

  • A single object or an array of exactly one object, in which case a 'standard' single part message is generated or
  • It is an array with >1 element in which case a multipart message is created, with each array element representing a different part.

Single Part

The 'msg.body' property is a single object or an Array object with one entry. The proprties should either be a string object or a Binary object. The properties are:

body.toString()StringThe string value of the object itself is the content of the body of the mail message.
body.contentTypeStringUsed for the 'Content-Type:' header.
body.base64encodeBooleanThe Presentation Engine will attempt to determine whether or not to base64 encode a portion of the body. The algorithm is very simple : If the contentType does not start with 'text/' then it will be encoded. Set this property to force encoding (or false to prevent encoding). Note the Presentation Engine is only capable of encoding Binary objects. (See RFC2045, section 6.8).
body.quotedPrintableBooleanFor text elements with this property set to 'true' the Whitebeam will apply "Quoted Printable" encoding to the text before it is sent built into the email (See RFC2045, section 6.7).

Multiple Part

More interesting condition is the multipart encoding. This is triggered if the 'msg.body' is an array that contains MORE THAN 1 element. In this case each entry in the array is treated in the following way:

body.toString()String/Binaryi.e. the content of the string object or the Binary object is used for the contents of this body item. base64 encoding is allowed ONLY if the item is a Binary object.
body[x].contentTypeStringThe mime-type for this element.
body[x].base64encodeBooleanOptional - if present with a value of 'true' *and* the element is a Binary object then the contents of the object will base 64 encoded out to the message. Note that using this mechanism means that the encoding is 'streamed' to the sendmail daemon and so no matter how large the body item - there will be no base64 encoiding held entirely in memory.
body[x].quotedPrintableBooleanFor text elements with this property set to 'true' the Whitebeam will apply "Quoted Printable" encoding to the text before it is sent built into the email (See RFC2045, section 6.7).
body[x].subTableObjectIf present Whitebeam will use the contents of the object to attempt text-substitutions on the message element. Substitution occurs by searching the body for instances of '$name' and then attempting to resolve 'name' as a property on the subTable. If found the $name is replaced by the value. This will generally be much faster and less resource hungry than attempting the same operation using regular expressions in JavaScript.
body[x].headersObjectHeaders for this content part. These are additional headers output immediately after the start of the part and before the body. This is where you can include 'Content-Disposition' etc

As of Whitebeam 1.2.1, each element of the 'body' array may itself be an array. This allows nested multi-part encoding to be achieved. This structure is required for those applications that wish to embed images into an email (using a 'multi-part/related' encoding).

©YellowHawk Ltd 2003-2005 : Whitebeam release 1.3.36
(loadtime : 14ms)