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.
wsBulk_doit(compositionFile,specs)
wsBulk_doit('',specs)
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. |
altFile if specified, is the name of php file that contains a function named ws_bulkEmailInit_read.
altFile should be either
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 ...
EXTAS should be specified in CSV string. There are a few (case insensitive) special values that can be used:
Examples: | extras='*' extras="REVIEW,CUSTOM,REPLACE,PREVIEW" |
joe@cool.com Joe Best <joe@cool.com>Whatever is specified will be displayed on the email composition form
messages should be an object with the following (case insensitive) fields:
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.
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
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>') ;
In particular, enter SMTP information; the From email address, and one or more To email addresses.
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).
Ambitious administartors can create their own email composition form.
.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' }