Reminders.
These are sent to participants who seem to have stopped
computing to your project, or who signed up but never got any credit.
Typically they would be short messages,
encouraging the participant to take a specific action.
Effective use of both types of email
is critical to maintaining and growing your participant base.
In the absence of any email, participation typically decreases
by a few percent every month.
The scripts provide the following features:
- They let you send different emails to different 'classes' of participants.
For example, you can send a different newsletter
to participants who haven't computed for your project in a while.
- They let you personalize emails,
e.g. by inserting the participant's name or their total credit.
- You can send multipart HTML/text messages.
- They provide a mechanism for inserting a
secure 'opt-out' link.
Note: You should ALWAYS include an 'opt-out' link
at the bottom of emails (both HTML and text).
In may be illegal for you to do a mass email without one.
Make sure you test this link.
The scripts requires that you use
PHPMailer,
is a PHP function for sending mail that's more full-featured
than the one built into PHP.
Download it, put it in html/inc, and set the
USE_PHPMAILER, PHPMAILER_HOST, and PHPMAILER_MAILER variables in
your project.inc file.
The general procedure for using each scripts is:
- Create a directory (mass_email or reminder_email)
in your html/ops/ directory.
In that directory, create separate files for
the text body template, HTML body template, and subject line
to be sent to each class of participants.
NOTE: the HTML files are optional;
if you leave them out, text-only emails will be sent.
-
Run the script in testing mode (see below)
to ensure that the emails are as you intend.
-
Once testing is complete, run the script in production mode.
Typically, the newsletter script is run from the command line.
The reminder script is typically run as a
periodic task, every 24 hours or so.
The scripts use the recent-average credit (expavg_credit) field
in the user table.
To make sure this value is accurate,
run update_stats manually
if you're not running it as a periodic task.
Personalizing emails
BOINC will replace the following macros in your email bodies
(both HTML and text):
";
list_start();
list_item("<name/>", "User name");
list_item("<create_time/>", "When account was created (D M Y)");
list_item("<total_credit/>", "User's total credit");
list_item("<opt_out_url/>",
"URL for opting out (this URL includes a salted version
of the participant's account key, and so is different for every participant).
");
list_end();
echo "
Avoiding spam filtering
Your email is less likely to be rejected by spam filters if:
- Your HTML and text versions have the same text.
- Your HTML version either contains no images,
or has at least 400 words.
Newsletters
The script html/ops/mass_email_script.php
is for sending email newsletters.
The script categorize participants as follows:
- Failed: zero total credit.
These people failed to download and install the client software,
or failed to get it working (e.g. because of proxy problems)
or uninstalled it before finishing any work.
- Lapsed: nonzero total credit but recent average credit < 1:
These people did work in the past, but none recently.
- Current: recent average credit >= 1.
These are your active participants.
To use the script, create the following files in html/ops/mass_email:
";
list_start();
list_item("failed_html",
"HTML message sent to failed users. Example: ".html_text(
"
Dear :
Test Project continues to do pioneering computational research
in the field of Submandibular Morphology.
In recent months we have discovered over 17 new varieties of Frombats.
Our records show that you created a Test Project account
on but that your computer hasn't completed any work.
Possibly you encountered problems installing or using the software.
Many of these problems have now been fixed,
and we encourage you to visit
our web site,
download the latest version of the software, and try again.
To not receive future emails from Test Project,
>click here.
"
)."
");
list_item("failed_text", "Text message sent to failed users.
Example: ".html_text("
Dear :
Test Project continues to do pioneering computational research
in the field of Submandibular Morphology.
In recent months we have discovered over 17 new varieties of Frombats.
Our records show that you created a Test Project account
on but that your computer hasn't completed any work.
Quite possibly you encountered problems installing or using the software.
Many of these problems have now been fixed,
and we encourage you to visit our web site,
download the latest version of the software, and try again.
To not receive future emails from Test Project, visit
"
)."
");
list_item("email_failed_subject", "Subject line sent to failed users.
Example: 'Test Project News'.
");
list_item("lapsed_html", "HTML message sent to lapsed users");
list_item("lapsed_text", "Text message sent to lapsed users");
list_item("lapsed_subject", "Subject line sent to lapsed users");
list_item("current_html", "HTML message sent to current users");
list_item("current_text", "Text message sent to current users");
list_item("current_subject", "Subject line sent to current users");
list_end();
echo "
Testing
Test your email before sending it out to the world.
As distributed, mass_email_script.php has the following
variables defined near the top:
\$testing = true;
Set it to false to actually send emails (rather than just print to stdout).
\$userid = 1;
If this is nonzero, email will be sent to the given user ID;
Otherwise it will be sent to all users.
To start, set \$userid to the ID of your own user record.
Run the script by typing
php mass_email_script.php
It will print (to stdout) the contents of all three email types
(failed, lapsed, and current).
Verify that the subject, HTML and text are correct.
Then set \$testing = false and run the script again.
You'll get three emails; check them.
Then set \$testing = false and \$userid = 0,
create an empty file called mass_email/log (see below),
and run the script.
You'll get voluminous output to stdout, but no emails will be sent.
Control-C it quickly if you want.
Make sure that each user is being sent the right type of email.
When you're sure that everything is correct,
set \$testing = false,
set mass_email/log to empty,
and run the script.
It will now send mass emails.
Depending on the size of your user table,
it may take hours or days to complete.
You can control-C it and restart whenever you want;
it automatically picks up where it left off (see below).
Checkpoint/restart
mass_email_script.php
manages checkpoint/restart when dealing with large numbers of participants.
Mails are sent in order of increasing user ID.
The file mass_email/log has a list of IDs that have been processed.
On startup, the script reads this file, finds the last entry,
and starts from there.
If you are starting a mass email from the beginning,
empty the file mass_email/log; i.e.
truncate mass_email/log
Reminder emails
The script html/ops/remind.php is for sending reminder emails.
The script categorizes users as follows.
- Failed: the account was created at least 14 days ago,
has zero total credit,
and hasn't received a reminder email in 30 days.
These people typically either had a technical glitch,
or their hardware and/or preferences didn't allow sending them work,
or the application crashed on their host.
The reminder email should direct them to a web page
that helps them fix these problems.
- Lapsed: the user has positive total credit,
hasn't done a scheduler RPC in the past 60 days,
and hasn't been sent a reminder email in the past 30 days.
They probably stopped running BOINC
or detached this project.
The reminder email should gently prod them to
start running BOINC and attach to this project again.
The numbers 14, 30, and 60 are all parameters in the script;
edit it to change them.
To use the script, create the following files in html/ops/reminder_email:
";
list_start();
list_item("failed_html", "HTML message sent to failed users");
list_item("failed_text", "Text message sent to failed users");
list_item("failed_subject", "Subject line sent to failed users");
list_item("lapsed_html", "HTML message sent to lapsed users");
list_item("lapsed_text", "Text message sent to lapsed users");
list_item("lapsed_subject", "Subject line sent to lapsed users");
list_end();
echo "
remind.php can be run as often as you like.
We recommend running it every hours, specifying it as a task in config.xml.
When it sends email to a user, it stores the time in their database record,
and won't send them another email for at least 30 days.
For this reason, it has no checkpoint/restart mechanism.
The procedure for testing your reminder email is
similar to that for email newsletters (see above).
";
page_tail();
?>