SendBlaster 3 and 4 come with a scripting engine that allows you to program your own tags using VBScript (familiar to Office users) or Javascript (familiar to web developers). These special tags can now contain conditional or calculated output, generate random variations, add custom attachments, and much more.
Important warning: This feature is intended for advanced developers only. Please use Scripts only if you are a developer and you are already confortable with scripting languages. Scripting is very powerful, in the right hands, but may also be dangerous: even a small mistake may cause major issues during the sending process. If you think that you will not use any scripts, a good idea is to disable the scripting engine: go to Advanced settings and check Disable scripting engine.
Please note that scripts use Microsoft's scripting library; in some cases, security tools (antivirus, antimalware programs) may regard scripting as a suspicious activity and raise an alert or disable the engine.
Main concepts
Scripts are special tags with short sequences of executable commands; they have a title and a source code.
The title of the script tells SendBlaster whether the script contains VBscript or Javascript code; it must always start with "vb:" (for VBscript) or "js:" (for Javascript). Only alphanumeric characters (no spaces) are allowed in the title.
The source code of the script is the actual code to be executed by SendBlaster.
You insert scripts by entering the script title in the message, either in the HTML code or in the readable text part, using the following notation (similar to SendBlaster's standard tags):
#vb:something#
or
#js:something#
Scripts are executed locally on your PC just before the message is sent out. The result is a standard email message, which does not require any scripting on the client's side.
As any programming language, scripts may return errors. SendBlaster deals with error in two different ways, depending on the context:
- If you are previewing the message (Preview button), the full error description is returned
- In actual messages, when you send out, no error is displayed – instead, the script does nothing.
This way, you can debug your scripts locally; but when you send out, the recipients will not see any ugly error even if the script fails.
Language reference
Vbscript
Tutorial: http://www.w3schools.com/vbscript/
Reference: http://www.w3schools.com/vbscript/vbscript_ref_functions.asp
Examples: http://www.w3schools.com/vbscript/vbscript_examples.asp
Javascript
Tutorial: http://www.w3schools.com/js/
Reference: http://www.w3schools.com/jsref/default.asp
Examples: http://www.w3schools.com/js/js_examples.asp
In addition to the standard features and objects included with the language, SendBlaster exposes some specific objects, properties and methods:
Objects
Contact
This object refers to the current recipient of the message.
Document
This object refers to the current message.
Important: this object overwrites the standard Document object found in Vbscript and Javascript; contrary to the standard object (which is used for manipulating a dynamic page, a feature that does not apply to an email context), it has only one method and no DOM or properties.
Properties
Contact.Field(index)
Contact.Field(fieldname)
index = 1 … 15
fieldname = the name of one of the fields (it is not case-sensitive)
Read-only property. Contains the value of the field.
If fieldname does not contain an existing field name, or index is out of range, an empty text is returned.
Contact.FileExists(path) (SendBlaster4 only)
path = the full path of a file.
Read-only property. Returns true if the specified file exists.
Contact.RandomWord(list)
list = a comma-separated list of words
Read-only property. Returns a random word from the list
Contact.Utf8Field(index) (SendBlaster4 only)
Contact.Utf8Field(fieldname) (SendBlaster4 only)
index = 1 … 15
fieldname = the name of one of the fields (it is not case-sensitive)
Read-only property. Contains the Ut8-encoded value of the field.
If fieldname does not contain an existing field name, or index is out of range, an empty text is returned.
Methods
Contact.AddAttachment path
path = the full path of a file
Adds an attachment to the message. The attachment is only sent to current recipient.
If the path is not valid, or another attachment with the same file name already exists in the message (even if it originally had a different path), no attachment is added.
Contact.SetField index, text (SendBlaster4 only)
index = 1 … 15
text = any text or variable
Temporarily replaces the original value of the field with the new text. The database is not affected, only the current message is.
Contact.Skip
The message is not sent to the contact: it is skipped.
If the message contains multiple scripts, the skipping occurs if at least one of the scripts calls this method.
(Note: When previewing the message – since there is no sending – a pop-up is displayed instead for debugging purposes)
Document.Write text
text = any text or variable
Writes something in the message.
Important: only the last Document.Write instruction in the script is executed; previous ones are ignored.
VBscript examples:
vb:salutation
if Contact.Field("Name") = "" Then
Document.Write "Dear user"
Else
Document.Write "Dear " & Contact.Field("Name")
End If