JSMail Help

JSMail Emailing component for VBScript v. 2.08.331

Help Updated 4-11-08

Introduction

JSMail is an ActiveX EXE component that can be used to send email.

What JSMail does:

JSMail.exe is designed for use with VBScript. It can send email in four ways:

• Plain text
• Plain text with file attachments.
• HTML webpage. (Text-only readers will see a notice that the mail is HTML only.)
• HTML webpage with embedded pictures.

V. 2 Update Note - 3/08:
There are a few updates in v. 2 that are especially focussed on sending HTML files as email. In the "HTML files" folder there is an HTA program, SendHTML.hta, for emailing webpages. The HTA includes full directions and is accompanied by a sample webpage. SendHTML.hta is designed for use by people who have experience writing webpage code and would like to apply that expertise to HTML email. Popular email programs have HTML email capability, but the options they provide are roughly equivalent to Wordpad: A dozen color options for text, the ability to choose fonts, and a small, ugly selection of background "stationery". If you write your own HTML email and import it into an email program, the code will usually be corrupted beyond repair. So the solution SendHTML.hta provides is to let you actually write a webpage, an HTML file, and then send that directly as an email without going through the half-baked HTML options in programs like Outlook Express or Thunderbird.

New in JSMail v. 2:

* Option for multiple recipients. (Multiple "To" recipients. No option for CC or BCC.)

* Recognizes images in STYLE tags with background-image property.

* Function SendTest and Property TestPathFolder provide a way to test custom-written HTML emails before sending.

Requirements

JSMail is compatible with Windows 95/98/NT4/ME/2000/XP. Vista is not supported.

First, register the component:

JSMail.exe must be registered on the system before use. To register the EXE file:
1) Put it in the System folder, or other safe place.
2) Drop it onto the RegSvrEXE.vbs script and click "Yes" in the message box that appears.

Basics of using JSMail

Create the object:

Set Mail = WScript.CreateObject("JSMail.Mailer", "JSM_")

   Note that WScript must be used in creating the object because it requires an event sink variable. Sending email is not an instantaneous process so there must be a way for the script to wait until the component notifies it that the procedure is finished.

   With the code above, JSM_ is assigned as the Event object. JSMail has one notable event: OnFinish

   Whether the emailing operation succeeds or fails, or if JSMail for some reason has trouble with Winsock, it raises the event OnFinish. JSMail also has a special property Busy that is specifically to provide WScript with something to do until OnFinish occurs. See below for details.

When finished with the object use:

Set Mail = Nothing

The JSMail object needs to be set to Nothing at the end of the script. Otherwise, as an ActiveX EXE, it can remain running.

Properties and Methods

Properties:

Read Property IsOnline - boolean. is Internet connection active?

Read Property IsConnectionProxy - boolean. is connection through a proxy server?

Read Property Busy - boolean. used to enable waiting for OnFinish event.

Write Property PlainText - boolean. whether plain text or HTML. Defaults to True, plain text.

Write Property Username - username for login, if different from FromEmail name. UserName is needed when login is required. Most servers these days require login with password.

Write Property Password - password for login, if necessary.

Write Property FromEmail - ex.: "ASmith@here.com" (Always required.)

Write Property FromName - ex.: "Al Smith"

Write Property ToEmail - ex.: "DJones@there.com" (Always required.) Multiple recipients can be addressed with a semi-colon-delimited string. Ex: "DJones@there.com;ASmith@there.com;JShmoe@somewhere.com"

Write Property ToName - ex.: "Dave Jones" . Optional "friendly name" for To email address. Multiple recipients can be handled with a semi-colon-delimited string. Ex: "Dave Jones;Al Smith;Joe S."

Write Property Server - ex.: "100.100.100.100" or "smtp.here.com" (Always required.)

Write Property Subject - ex.: email subject

Write Property Port - port to send from. This is standard the port 25 unless set otherwise.

Write Property TestPathFolder - (New in v. 2) Path to an existing folder where test email will be written by the SendTest method. This property must be set to a valid folder path before calling SendTest.

Special case properties:

Write Property Verbose - For debugging use only. Verbose = True causes a report of server exchange. Default value = False. When Verbose is set to True OnTalk event must be used to receive text of server conversation. (see below)

Write Property BypassPassword - Special case usage.

   BypassPassword will cause JSMail to ignore a server request for password. This property is not used under normal circumstances. It is included because in some cases there may be trouble with the password function due to server software. One person wrote who was using a program called "Mailsweeper" that was causing JSMail to fail. The details:

   When logging onto an SMTP server the client sends "EHLO", which essentially means "Hello?" If the server returns the line "AUTH" as part of its response that means that a password is used. What follows "AUTH" will be the types of password encoding that are accepted.

   When JSMail logs on, if it receives "AUTH" but Property Password has no value then it will quit with the error message: "Password required." What appears to happen in some cases is that spam filters and similar software are sometimes set up to take charge of the mail server and may not properly translate server messages. In the case of the problem with the Mailsweeper program, apparently the server was sending "AUTH" and Mailsweeper was taking care of the password stage of communication, but Mailsweeper was neglecting to then remove "AUTH" from the server communication coming through to JSMail. The result was that JSMail was expecting to send a password where none was needed and none had been entered.

   When BypassPassword is set to True, JSMail will act as though "AUTH" was not received in the EHLO response, regardless of whether it was or not. In other words, JSMail will just proceed to send the email and leave out any password functionality.

( The Server, FromEmail and ToEmail properties are the minimum requirement to send an email.)

Methods:

Sub PrepareEmail(sBodyOfEmail, sFileList)

sBodyOfEmail - actual text of email, or HTML if an HTML email. Note: When sending an HTML email with pictures embedded the IMG and/or BODY BACKGROUND attributes must be filename only, within quotes. Do not use full path and do not leave unquoted, or picture will not appear in email. ex.: <IMG SRC="pic1.gif" WIDTH=30....etc.

JSMail will recognize 3 kinds of embedded images in HTML, and will write the email accordingly:

1) <IMG SRC="pic1.gif" (use only file name - no path - and put in quotes.)

2) <BODY BACKGROUND="pic1.gif" (use only file name - no path - and put in quotes.)

3) Style background-image property. You can use a background image for a CSS element. The syntax must be:
background-image: url(pic1.gif); (Use file name only - no path - and do not use quotes.)

Note: In tests the background-image property in a STYLE tag was recognized by Outlook Express 5 and 6, and by Mac email, but was not recognized by Thunderbird 1.5. No tests were done with "webmail". If you use background-image in an email it may be a good idea to design the given background so that it also looks good without the image, in case one of your recipients is using a non-conformant email program.

sFileList - In a plain text email sFileList is an optional list of file attachments. In an HTML email sFileList is an optional list of GIF, JPG, or PNG pictures embedded in the webpage. The file list must be a single string of full paths, delimited by an asterisk (*). If full, accurate path is not used then JSMail will not find the file and it will be ignored. No error will be raised. Example sFileList:
"C:\pictures\pic1.gif*C:\pictures\pic2.jpg*C:\pictures\picother.gif"
If no files are to be sent use "" for sFileList.

PrepareEmail sends the text of the email to JSMail, along with a list of files if included. PrepareEmail should be used after desired properties have been set, before Send is used.

Sub Send - connects and sends email.

Function SendTest(ErrorInfo) - (New in v. 2) JSMail v. 2 is designed for easily sending entire webpages directly as email. In order to help with that. the SendTest function provides the ability to write a test email to disk in order to check your HTML, syntax, spelling, etc. before sending the email.

SendTest returns a numeric value:
0-success.
1-folder path not validly set in TestPathFolder property.
2-PlainText property is set to True. (PlainText must be False because SendTest is only for HTML email.) other number- system error.

If return is not 0, indicating an error, the ErrorInfo parameter will include an error description.

Events:

Event OnFinish(Success, sError)
Occurs when JSMail is done, whether mail was sent or not.

Success - True if mail was successfully sent. False if not.

sError - If Success is False, sError contains a string error report.

Event OnTalk(vData)

OnTalk is an optional event only for debugging. If Verbose is set to True then OnTalk will fire whenever data is sent or received in communication with server. vData will be the string communicated, prefaced by "In:" or "Out:" to denote source of communication.

Recommended usage: When it's desirable to log server communication, create a text file before sending email:

     ...
       Set TS = FSO.CreateTextFile("C:\ELog.txt") '-- create log file here.
       Mail.Send
         While Mail.Busy = True
         Wend
           ...etc.

Then include the OnTalk event sub to write log data as it arrives:

       Sub JSM_OnTalk(vData)
         TS.WriteLine vData
       End Sub

Finishing a send operation:

Bugfix note: If you have used JSMail before and experienced a crash of the script at the very end, change your code according to the directions below. The original code samples had the script ending from inside the OnFinish event sub. That seems to be the cause of crashing.

To finish a send, set a global Boolean variable in the OnFinish sub so that the script knows when to quit. In the sample script, sender.vbs, a waiting loop runs until the global variable FinishDone is set to True.

  
   Set Mail = WScript.CreateObject("JSMail.Mailer", "JSM_")
   ...
     Set JSMail properties as needed here...
   ...
   
    '-- Call Mail.Send here and wait for Mail.Busy to become False.
   
  '-- Then wait for signal that the OnFinish event has fired, which means the object
  '-- can be disconnected and set to nothing. (Disconnect to stop events before closing log file.)
  
   While FinishDone = False
   Wend

  WScript.DisconnectObject Mail
  Set Mail = Nothing
   
   If (IsV = True) Then '-- if Verbose = True then close log file here.
       TS2.Close
       Set TS2 = Nothing
   End If  
       
   Set FSO2 = Nothing 
   WScript.Quit  
   
  ' ------ end of script.
  
     Sub JSM_OnFinish(Success, sError)
        If (Success = True) Then
            MsgBox "Email sent."
        Else
            MsgBox "JSMail error:" & vbcrlf & sError 
        End If
          FinishDone = True
     End sub

See the included sample script sender.vbs for full demo.

Limitations

You must be online and cannot be using a proxy server when sending email. JSMail does not find an email server or provide one. You must provide that, just as you would with an email program.

There are no options to send CC or BCC with JSMail, but you can send to multiple recipients using "To".

License

You use all script code and components from JSWare at your own risk.

   The components (compiled DLL and EXE files) may be used for personal or commercial purposes. No payment or attribution is required for either use. The components may be redistributed if they are required as support files for scripts or software that you have written.
   Also, the script code may be used freely, in part or as whole scripts, for any purpose, personal or commercial, without payment or attribution.

   I ask only that you not redistribute these scripts and components, except as required for your direct use. Instead, please direct others to obtain copies of JSWare scripts and components directly from www.jsware.net.

   Also, none of the code here may be redistributed under another license. If a work using code from JSWare is distributed with restrictions of any kind the code from JSWare must be kept exempt from those restrictions. This includes, but is not limited to, code sold for profit, code with usage restrictions and code distributed as so-called "Open Source" with redistribution restrictions.
Joe Priestley