Using wsurvey_bulkEmail: a bulk email package

wsurvey_bulkEmail is a set of javascript and php library files that are part of the wSurvey suite. If wSurvey is properly installed, you don't need to install additional files.

wsurvey_bulkEmail is used to implement bulk emailing -- that is, broadcasting emails to a number of recipients. You will need to write a php script that uses these library files.

wsurvey_bulkEmail makes it relatively easy to add a web-centric list server to a software package.
Features
The notion of wsurvey_bulkEmail is to make it easy for a set of end users (the people who want to email to each other) to select who to send emails to, compose an email, and deliver it -- all within a fairly standard web interface. wsurvey_bulkEmail features include:
Basic setup
wsurvey_bulkEmail is a set of libraries used by a php script you create. Let's call this script myBroadcast.php.
myBroadcast.php must contain the following declarations
What does your script need to do?
Your script (myBroadcast.php) provides the front-end to wsurvey_bulkEmail. But it doesn't need to do much. That is: assuming you are not going to tweak some advanceed optons, to use wsurvey_bulkEmail you need to:
The specs parameter
The specs parameter in wsBulk_doit is used to specify a variety of parameters and options. specs should be an object, with the following (case insensitive) fields:
altFile Optional. Absolute or relative name of php file containing a php file that will augment specs
altParams Optional. Parameters to sent to the altFile
container Optional. id of outer container -- it will be .show(). If not specified, wsBulk_composeBox is used (it will be created if necessary)
containerInner Optional.id of container to write the email composition form. If not specified, wsBulk_composeBox_inner is used (it will be created if necessary)
extras Optional. A CSV string specifying what extra features are allowed (details below)
from Required. Email address, and name, of author of email.
It can be a string containing a name and email address. Or, for greater flexibilty: an associative array with EMAIL,NAME, and DISPLAY fields.
messages Optional. Pre-fill subject and messages fields. An associate array with TEXT, HTML, SUBJECT, and SEND_HOW fields.
replace_1 Optional. Replacement key codes descriptive message (for a first set of keycodes)
replace_2 Optional. Replacement key codes descriptive message (for a second set of keycodes)
replace_3 Optional. Replacement key codes descriptive message (for a third set of keycodes). This is typically reserved for temporary keycodes (created by the end-user)
replace_messages Optional. A CSV string of 3 parts: each part is used as header to explain the REPLACE_1, REPLACE_2, and REPLACE_3 sets of keycodes
replace_where Optional. A CSV string specifying where to do mailmerge (process keycode replacements). 4 areas can be specified: S (the subject), H (the html message), T (the text message), A (all attachments).
The default is S,T,H (do replacements in everything except attachments).
replacements_data Optional. An associative array of objects. Each row in the associative array has an email address as a key, within each row fields define keyvalues
reply_to Optional. The email (and name) to use in the Reply-To: header. As with FROM, as a string or an object with NAME and EMAIL fields. Typically, this is where replys are sent to. If missing or '', use FROM
return_path Optional. The email to use in the Return-Path: header. Typically, this is the email for the "bounce handler" for the site that is doing the bulk email
review_box Optional. Where to display review of email subject, etc. If not specified, wsBulk_reviewBox is used (and is created if need be)
reviewFunc Optional. A string containing the name of the function to call after submit button is clicked. If '', or not specified: use built in wsBulk_reviewMessage.
reviewFunc is an advanced administrators parameter, and is not typically used. For details, see the comments in wsurveyBulk_email.js and wsureyBulk_email.php
smtpInfo Conditionally required. It is required, but may be better specified in the altfile. Should be an object with SMTP info in fields: GATEWAY, PORT, USERNAME, and PASSWORD
submit_message Optional. Text of the button. is the default
sender Optional. The email address to use in a Sender: header. Typically, this is the email address for the site that is doing the bulk email
to Required. Email addresses, and names, of recipient(s) of email. Can be a CSV string, where each part contains the email address, and name, of a recipioent.
Or, for greater flexibilty: each array where each row is an object with EMAIL,NAME, and DISPLAY fields.
to_header Optional. Header message to display above list of recipients.
The specs parameter: details
The following describes the more complex specs fields (the other fields are fairly self-explanatory). Note that specs fields are case insensitive (so the following descriptions may use upper case, or camelCase).
altFile is used to specify a php file that can be used to augment the specs parameter. altParams are parameters to pass to this function.
Typical uses of an altFile:
  1. set the smtpInfo parameters -- a useful trick since you probably don't want to expose these parameters in your javascript code!
  2. add additional variales to replacements_data -- such as permanent recipient specific variables stored in a mysql database on the server

altFile if specified, is the name of php file that contains a function named ws_bulkEmailInit_read.

altFile should be either

  1. a fully qualified file name -- if it exists, it is used
  2. or specified relative to the root of your www directory (looked for if no fully qualified filename is found)
Thus if the file is d:\wwww\mystuff\doit.php, and d:\www is the root of the web directory, you could use either:
  • d:/wwww/mystuff/doit.php (note that / is safer to use then \ )
  • or /mystuff/doit.php
  • The ws_bulkEmailInit_read function can augment, or modify, parameters set in specs; and it can use altParams to figure out just what to do.
    ws_bulkEmailInit_read should return an array of: [status,changes]
    where ...

  • status: a 1 or an error message. If anything other than a 1 the status is displayed and processing stops.
  • changes: an object containing one or more of the following (case insensitive) fields:
  • echo: a 0/1 variable. 0 = do not send a bcc of each email to the sender. 1=send these bcc emails
  • from : an object with NAME and EMAIL fields
  • message : the text message
  • messageHtml: the html message
  • mailMerge: a 0/1 variable. 0 = do not do mail merge (keycode replacements). 1=do them
  • replacements an object containing mailmerge (keycode) values. It augments the REPLACEMENTS_DATA in specs
  • return_path : an object with an EMAIL field
  • sender : an object with an EMAIL field
  • subject : a string containing the subject.
  • to : an array, each row is an object with NAME and EMAIL fields
  • Note that values specified by ws_bulkEmailInit_read will overwrite values specifed in specs.

    Simple example -- used to keep smtpInfo private (so it doesn't need to be written in myBroadcast.php):

     function ws_bulkEmailInit_read($altParams) {
       $elist=[];
       $smtpInfo=['GATEWAY'=>'smtp.mysite.org',
                  'PORT'=>2525,
                  'USERNAME'=>'admin@mysite.org',
                  'PASSWORD'=>' goober '];
      $elist['smtpInfo']=$smtpInfo;
      return [1,$elist];
    }
    
  • EXTRAS is used to specify what features will be available to the end-user (who is composing the email). You could use the grant the same features to all end-users, or grant different features to different end-user s(say, only allow administartors to add attachments).

    EXTAS should be specified in CSV string. There are a few (case insensitive) special values that can be used:

    • *: all extra features enabled.
    • NONE: no extra features (all are disabled). If used, should be first item in the CSV -- you can then enable selectively
    • DEFAULT: default extra features enabled: mailMerge (keycode replacements) in subject,text, and html; review mode available. Should be first item in the CSV
    Individual features can be enabled using the following (case insensitive) values:
    • ATTACH : file attachments allowed
    • CUSTOM : allow specification of custom mail merge replacements.
    • ECHO : echo back to sender (using BCC) allowed
    • EDIT : allow editing in REVIEW mode (allows the end-user to edit each recipient's email)
    • HTML_ALL : allow "unsafe" html (i.e.; <script> tags). Otherwise, potentially unsafe tags (and attributes) are removed
    • PREVIEW : preview enabled in REVIEW mode. Allows end-user to view each recipient's email, including mailmerge (keycode) replacements
    • REVIEW : allow review (including edit and preview), and 1-at-a-time sending, of emails. Otherwise, all emails are sent at in sequence (though pause and resume are alllwoed)
    • STATUS : permit viewing of status information (i.e.; SMTP messages)
    • Only one of REPLACE_ALL, REPLACE_DFAULT or REPLACE_NONE should be specified. If more than one, the last in the list is used
    • REPLACE_ALL : mail merge replacements on all four "areas": subject, text message, html message, attachments
    • REPLACE_DEFAULT (or just REPLACE) : mail merge replacements on three "areas": subject, text message, html message.
    • REPLACE_NONE : no mail merge replacements; follow with one of the following to specify exactly
    • These can be specified after one of the above (this is typically used after REPLACE_NONE, to specify exactly which areas to process for replacements)
    • REPLACE_HTML : mail merge replacements on html messages
    • REPLACE_TEXT : mail merge replacements on text messages
    • REPLACE_SUBJECT : mail merge replacements on subject
    • REPLACE_ATTACH : mail merge replacements on attachments

    Examples:
      extras='*'
      extras="REVIEW,CUSTOM,REPLACE,PREVIEW"
    

    FROM is used to specify the sender of the email. It is required.
    FROM can have two formats:
    • As a string, with email and (optionally) name.
      Examples:
       joe@cool.com
       Joe Best <joe@cool.com>
      
      Whatever is specified will be displayed on the email composition form
    • As an object with the following fields:
    • NAME : The name of the sender. For example : Joe Best
    • EMAIL : The email of the sender. For example : joe@cool.com
    • DISPLAY : What to display on the email composition form. For example : Your pal Joe
    • Using DISPLAY allows the sender to have some anonymity (for example, if you do not want to display his email address).
    messages is used to pre-fill the subject, text messages, and html message fields in the email composition form. It is also used to force immediate delivery (using these pre-filled values.

    messages should be an object with the following (case insensitive) fields:

  • HTML A string that will be written to the html message <textara>.
  • TEXT A string that will be written to the text message <textara>. Thus, when the end-user opens the email composition form, the text message <textarea> will be pre filled with this value.
  • SUBJECT A string that will be written to the subject line
  • SEND_HOW A string that instructs how the message should be sent. Allowable values are:
  • PREFILL : Pre fill using the TEXT and other fields. The end-user can then modify these values. This is the default (it is used if SEND_HOW is not specified
  • ASIS: PREFILL, and then skip to the Review. Basically, this simulates a click on the Send this message button.
  • READY ASIS, and then skip to the PREVIEW/EDIT/SEND (for each recipient) screen. Basically, this simulates a click on the Review button.
  • SEND ASIS, and then immediately start emailing. Basically, this simulates a click on the Send! button.
  • SENDQUIT SEND, and then close the wsBulk screens. Basically, this simulates a click on the Close! button.
  • replacements_data is used to specify the mailmerge (keycode replacements). One can specify seperate replacements for each recipient.

    Structure of replacements_data
    replacements_data is an associative array. Each row of this array specifies replacements for an email address. The field for these rows should be the (case sensitive) email addresses of the recipients.
    Each row should be an object, with fields corresponding to keycodes.

    Example:

      replacement_data=[];
       replacement_data['joe@foo.com']=[];
       replacement_data['joe@foo.com']['SIZE']='6 feet';
       replacement_data['joe@foo.com']['WEIGHT']=' not heavy';
     
    These are used in mail merges -- if {KEYNAME} matches a 'varname' (such as SIZE specified for the recipient, then {KEYNAME} is replaced by the appropriate value.
    Note: replacements['*']['SOMENAME'] :: * is used as the default (if a recipient does not have a SOMENAME specified)
    TO is used to specify the recipients of the email. It is required.
    TO can have two formats:
    • As a CSV string, with each part containing the email and (optionally) a name.
      Example:
       bog@somewhere.org,  Bill Sill <bsill@nowhere.org>, jake@joke.net , The admin <admin@mysite.org>
      
      Whatever is specified will be displayed on the email composition form
    • As an associative array, with each row an object with the following fields (the same as in FROM:
    • NAME : The name of the recipient. For example : Bill Sill
    • EMAIL : The email of the sender. For example : bsill@nowhere.org>
    • DISPLAY : What to display on the email composition form. For example : Bill Sill<
    • Using DISPLAY allows the recipients to have some anonymity (for example, if you do not want to display their email addresses).
    Hints & tips
    The wsBulk_setParam_splitAddress function
    wsBulk_setParam_splitAddress is used to split a string containing an email into an object with NAME and EMAIL fields.
    Useage: aobj=wsBulk_setParam_splitAddress(emailString)

    Examples:

        aobj= wsBulk_setParam_splitAddress('bob@somewhere.net') ;  : would yield aobj['NAME']='', aobj['EMAIL']='bob@somewhere.net'
        aobj= wsBulk_setParam_splitAddress('My Cat <meow@mysite.org>') ;  : would yield aobj['NAME']='My Cat', aobj['EMAIL']='meow@mysite.org>'
        
        specs['from']=wsBulk_setParam_splitAddress('My Cat <meow@mysite.org>')  ;
    
     
    wsurvey_bulkEmail_demo.htm ( in /wsurvey/jsLib/)
    wsurvey_bulkEmail_demo.htm is a simple demo program. To use it, edit it with a text editor and modify the variables in the customizable parameters section.

    In particular, enter SMTP information; the From email address, and one or more To email addresses.

    wsurvey_bulkEmail_quick.htm ( in /wsurvey/jsLib/)
    wsurvey_bulkEmail_quick.htm is a simple demo program that show how wsurvey_bulkEmail can be used without end-user interaction. That is: to send a pre-composed email to a number of recipients (i.e.; something specified by an administrator in a javascript file). fs

    As with wsurvey_bulkEmail_demo.htm, before using this you must edit it. In addition to the SMTP information, and email addresses, you should enter the text message and subject lines, and chose how the message should be sent (for example, should a review screen be displayed).

    The email composition file
    The email composition file specifies the email composition form. It is specified as the first argumeint in wsBulk_doit.
    By default (if '' is used): ws_bulkEmailForm.inc (in /wsurvey/phpLib) is used.

    Ambitious administartors can create their own email composition form.

    Since this form contains a number of special identifiers, it is safest to start with ws_bulkEmailForm.inc, and pay attention to the comments and the ids (that start with wsBulk_ in the <input ... > and other elements.
    Default CSS classes
    The following CSS classes are used if they are not defined (i.e.; if they are not specified in a <style> section in myBroadcast.php).

    .wsBulk_htmlAtCaret   {
            {'background-color':'#dfdedf';
           'margin':'3px 5px 3px 3px
    }
    
    .wsBulk_keycodeAtCaret  {
           {'background-color':'#cfc9cf';
            'margin':'3px 5px 3px 6px';
            'font-family':'monospace
    }
    
    .wsBulk_keycodeAtCaret:after  {
            {'content': "'}'";
            'color':'blue'
    }
    
    .wsBulk_keycodeAtCaret:before {
            {'content': "'{'";
            'color':'blue'
    }
    
    .wsBulk_submitOuter  {
            {'background-color':'lime';
            'padding':'3px';
            'margin':'5px 5px 5px 5px'
    }
    
    .wsBulk_review1':
          { 'border':'5px dotted p';
            'margin':'5px 5% 5px 5%';
            'padding':'10px'
    }
    
    
    .wsBulk_composeboxClass  {
          {'position':'fixed';
           'display':'none';
           'overflow':'auto';
           'z-index':'55';
           'left':'3%';'top':'10%';
           'width':'92%';'height':'80%';
           'margin':'10px;padding:8px';
           'border':'2px solid gold';
           'background-color':'#ededed';
           'border-radius':'5px';
           'box-shadow':'10px 10px 15px 10px tan'
    }
    
    .wsBulk_reviewboxClass' {
          {'position':'fixed';
          'display':'none';
          'z-index':'66';
          'left':'6%';'top':'30%';
          'width':'88%';'height':'60%';
          'margin':'10px;padding:8px';
          'border':'2px solid blue';
          'background-color':'#bdcdbd';
          'border-radius':'5px';
          'overflow':'auto';
          'box-shadow':' 5px 5px 5px 5px cyan'
    }
    
    .wsBulk_nsentClass' {
          {'font-family':'monospace';
           'font-size':'90%';
           'background-color':'#dadada';
           'font-weight':'400'
    }
    
    .wsBulk_nskipClass'  {
          {'font-family':'monospace';
          'font-size':'90%';
          'background-color':'#fafada';
          'font-weight':'400'
    }
    .wsBulk_sendButton {
          {'border':'2px solid green';
          'background-color':'lime';
          'padding':'2px';
          'margin':'2px'
    }