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
Previous version of the Whitebeam system have included basic access to email via the
Message Template. The advantages of this new
- 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:
|operation||Number||Takes one of three possible values to tell the Presentation Engine how to process a requuest. For details
see the description
in the SmtpRequest definition.|
|HELO||String||The domain name sent to SMTP as part of the HELO (or EHLO) introduction|
|envFrom||String||Used in the SMTP MAIL FROM: command. If this value is not specified then the value of the
'sender' property is used. If there is no Sender header then the value of the 'from' property is used.
Introduced in Whitebeam release 1.3.5|
|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.|
|to||Array||One of theese *must* exist and be non-empty. Each address is a string object containing the target email address.|
|cc||Array||Contents of the 'CC' header *and* added to the RCPT TO: if envTo not
|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.
|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'|
|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
|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.
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
|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).|
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
|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).