Whitebeam e-mail control through SmtpRequest class.

Site Map

Home

Application Guide
	Quick Start
	PHP and ASP
	Writing Apps
	Applications
	Tutorials
		Replication
		Postgres Interface
		XML Processing
		Using XPath
		Binary Object
		Using HttpRequest
		SmtpRequest
		Session
		Meta Data
		Iterators
		Memb Services
		Page Look&feel
		Authentication+
		Questionnaires
		Message Groups
		Form Handling
	Samples
Reference
Community
Contact Whitebeam
To-Do
Download
Credits
Licence
Whitebeam Users

Whitebeam e-mail control through SmtpRequest class.

Subject

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.to	Array	One of theese must exist and be non-empty. Each address is a string object containing the target email address.
msg.envTo	Array
msg.cc	Array	Contents of the 'CC' header and added to the RCPT TO: if envTo not set.
msg.bcc	Array	Added to the RCPT TO: if envTo not set, otherwise ignored.
rawData	Boolean	If 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
defaultText	String	Used in two different ways: If the message is a multi-part encoding then this property is inserted into the message before the start of the first part. 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.multipart	String	If 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.
subject	String	Subject: header. Ignored if rawData is 'true'
replyTo	String	Reply-To: header. Ignored if rawData is 'true'
from	String	From: header. Also used as the 'MAIL FROM:' envelope header if there is no 'sender' property. Ignored if rawData is 'true'.
sender	String	If present then this is put into the 'MAIL FROM:' envelope header and overrides the 'from' value.
headers	Object	Each 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).
body	Object or Array	Used 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()	String	The string value of the object itself is the content of the body of the mail message.
body.contentType	String	Used for the 'Content-Type:' header.
body.base64encode	Boolean	The 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.quotedPrintable	Boolean	For 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/Binary	i.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].contentType	String	The mime-type for this element.
body[x].base64encode	Boolean	Optional - 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].quotedPrintable	Boolean	For 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].subTable	Object	If 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].headers	Object	Headers 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).

View XML source of this page

(loadtime : 7ms)