Beatitude - Scheduled Mailings
- NAME
- Obtaining The Plugin
- Description
- REQUIREMENTS
- Installation
- Lightning Configuration/Installation Instructions
- Manual Installation
- Configuring the Cronjob to Automatically Run Beatitude
- Command Line Interface
- Misc. Options
- Debugging
- FAQs
- COPYRIGHT
NAME
Beatitude - A Scheduled Mailer for Dada Mail
Obtaining The Plugin
Beatitude is located in the, dada/plugins directory of the Dada Mail distribution, under the name: scheduled_mailings.pl
Description
Beatitude is a plugin for Dada Mail that allows you to compose email messages to be scheduled for sending in the future.
Highly configurable, messages themselves can be in PlainText, HTML or multipart/alternative and have an unlimited number of attachments. The message itself can be composed in the plugin itself, fetched from a file or from a webpage.
The schedules themselves can be anywhere from one minute to years into the future and can be repeated infinitely. Schedules also have many safegaurds to help send only new content; for example: if a scheduled mailing is created to send the contents of a URL once a day, it will only send that URL if the contents are different from the previous day.
REQUIREMENTS
Familiarity with setting cron jobs
If you do not know how to set up a cron job, attempting to set one up for Beatitude will result in much aggravation. Please read up on the topic before attempting!
The Storable Module
If you have perl 5.8, this should already be installed. If it's not, you can grab it here:
http://search.cpan.org/~ams/Storable
Shell Access to Your Hosting Account
Shell Access is sometimes required to set up a cronjob, using the:
crontab -e
command. You may also be able to set up a cron tab using a web-based control panel tool, like Cpanel.
Shell access also facilitates testing of the program.
Installation
This plugin can be installed during a Dada Mail install/upgrade, using the included installer that comes with Dada Mail. The below installation instructions go through how to install the plugin manually.
If you do install this way, note that you still have set the cronjob, which is covered below.
Lightning Configuration/Installation Instructions
To get to the point:
Upload the scheduled_mailings.pl script into the cgi-bin/dada/plugins directory (if it's not already there)
chmod 755 the scheduled_mailings.pl script
run the plugin via a web browser.
Set the cronjob
Manual Installation
Configuring scheduled_mailings.pl Plugin Side
Change permissions of "scheduled_mailings.pl" to 755
The, scheduled_mailings.pl
plugin will be located in your, dada/plugins diretory. Change the script to, 755
Configure your .dada_config file
Now, edit your .dada_config
file, so that it shows the plugin in the left-hand menu, under the, Plugins heading:
First, see if the following lines are present in your .dada_config
file:
# start cut for list control panel menu
=cut
=cut
# end cut for list control panel menu
If they are, remove them.
Then, find these lines:
# {
# -Title => 'Scheduled Mailings',
# -Title_URL => $PLUGIN_URL."/scheduled_mailings.pl",
# -Function => 'scheduled_mailings',
# -Activated => 1,
# },
Uncomment the lines, by taking off the, "#"'s:
{
-Title => 'Scheduled Mailings',
-Title_URL => $PLUGIN_URL."/scheduled_mailings.pl",
-Function => 'scheduled_mailings',
-Activated => 1,
},
Save your .dada_config
file.
Configuring the Cronjob to Automatically Run Beatitude
We're going to assume that you already know how to set up the actual cronjob, but we'll be explaining in depth on what the cronjob you need to set is.
Setting the cronjob
Generally, setting the cronjob to have Beatitude run automatically just means that you have to have a cronjob access a specific URL. The URL looks something like this:
http://example.com/cgi-bin/dada/plugins/scheduled_mailings.pl?run=1&verbose=1
Where, http://example.com/cgi-bin/dada/plugins/scheduled_mailings.pl is the URL to your copy of scheduled_mailings.pl
You'll see the specific URL used for your installation of Dada Mail in the web-based control panel for Beatitude, under the fieldset legend, Manually Run Beatitude. under the heading, Manual Run URL:
This will have Beatitude check any awaiting messages.
You may have to look through your hosting account's own FAQ, Knowledgebase and/or other docs to see exactly how you invoke a URL via a cronjob.
A Pretty Good Guess of what the entire cronjob should be set to is located in the web-based crontrol panel for Beatitude, under the fieldset legend, Manually Run Beatitude, under the heading, curl command example (for a cronjob):
From my testing, this should work for most Cpanel-based hosting accounts.
Here's the entire thing explained:
In all these examples, I'll be running the script every 5 minutes ( */5 * * * * ) - tailor to your taste.
Using Curl:
*/5 * * * * /usr/local/bin/curl -s --get --data run=1 --url http://example.com/cgi-bin/dada/plugins/scheduled_mailings.pl
Using Curl, a few more options (we'll cover those in just a bit):
*/5 * * * * /usr/local/bin/curl -s --get --data run=1\;verbose=0\;test=0 --url http://example.com/cgi-bin/dada/plugins/scheduled_mailings.pl
$Plugin_Config->{Allow_Manual_Run}
If you DO NOT want to use this way of invoking the program to check awaiting messages and send them out, make sure to change the variable, $Plugin_Config-{Allow_Manual_Run}> to, 0:
$Plugin_Config->{Allow_Manual_Run} = 0;
at the top of the scheduled_mailings.pl script. If this variable is not set to, 1 this method will not work.
Security Concerns and $Plugin_Config->{Manual_Run_Passcode}
Running the plugin like this is somewhat risky, as you're allowing an anonymous web browser to run the script in a way that was originally designed to only be run either after successfully logging into the list control panel, or, when invoking this script via the command line.
If you'd like, you can set up a simple Passcode, to have some semblence of security over who runs the program. Do this by setting the, $Plugin_Config-{Manual_Run_Passcode}
variable in the scheduled_mailings.pl source itself.
If you set the variable like so:
$Plugin_Config->{Manual_Run_Passcode} = 'sneaky';
You'll then have to change the URL in these examples to:
http://example.com/cgi-bin/dada/plugins/scheduled_mailings.pl?run=1&passcode=sneaky
Other options you may pass
You can control quite a few things by setting variables right in the query string:
passcode
As mentioned above, the
$Plugin_Config-{Manual_Run_Passcode}
allows you to set some sort of security while running in this mode. Passing the actual password is done in the query string:http://example.com/cgi-bin/dada/plugins/scheduled_mailings.pl?run=1&passcode=sneaky
verbose
By default, you'll receive the a report of how Beatitude is doing checking the schedules and if it does send out one.
This is sometimes not so desired, especially in a cron environment, since all this informaiton will be emailed to you (or someone) everytime the script is run. You can run Beatitude with a cron that looks like this:
*/5 * * * * /usr/local/bin/curl -s --get --data run=1 --url http://example.com/cgi-bin/dada/plugins/scheduled_mailings.pl >/dev/null 2>&1
The, >/dev/null 2>&1 line throws away any values returned.
Since all the information being returned from the program is done sort of indirectly, this also means that any problems actually running the program will also be thrown away.
If you set verbose to, ``0'', under normal operation, Beatitude won't show any output, but if there's a server error, you'll receive an email about it. This is probably a good thing. Example:
* * * * * /usr/local/bin/curl -s --get --data run=1\;verbose=0 --url http://example.com/cgi-bin/dada/plugins/scheduled_mailings.pl
test
Runs Beatitude in test mode by checking the messages awaiting and parsing them, but not actually carrying out any sending.
Notes on Setting the Cronjob for curl
You may want to check your version of curl and see if there's a speific way to pass a query string. For example, this:
*/5 * * * * /usr/local/bin/curl -s http://example.com/cgi-bin/dada/plugins/scheduled_mailings.pl?run=1&passcode=sneaky
Doesn't work for me.
I have to use the --get and --data flags, like this:
*/5 * * * * /usr/local/bin/curl -s --get --data run=1\;passcode=sneaky --url http://example.com/cgi-bin/dada/plugins/scheduled_mailings.pl
my query string is this part:
run=1\;passcode=sneaky
And also note I had to escape the, ; character. You'll probably have to do the same for the & character.
Finally, I also had to pass the actual URL of the plugin using the --url flag.
Command Line Interface
There's a slew of optional arguments you can give to this script. To use Beatitude via the command line, first change into the directory that Beatitude resides in, and issue the command:
./scheduled_mailings.pl --help
Command Line Interface for Cronjobs:
One reason that the web-based way of running the cronjob is better, is that it doesn't involve reconfiguring the plugin, every time you upgrade. This makes the web-based invoking a bit more convenient.
#1 Change the lib path
You'll need to explicitly state where both the:
Absolute Path to the site-wide Perl libraries
Absolute Path of the local Dada Mail libraries
I'm going to rush through this, since if you want to run Beatitude this way you probably know the terminology, but:
This script will be running in a different environment and from a different location than what you'd run it as, when you visit it in a web-browser. It's annoying, but one of the things you have to do when running a command line script via a cronjob.
As an example: use lib qw()
lines probably look like:
use lib qw(
../
../DADA/perllib
../../../../perl
../../../../perllib
);
To this list, you'll want to append your site-wide Perl Libraries and the path to the Dada Mail libraries.
If you don't know where your site-wide Perl libraries are, try running this via the command line:
perl -e 'print $_ ."\n" for @INC';
If you do not know how to run the above command, visit your Dada Mail in a web browser, log into your list and on the left hand menu and: click, About Dada Mail
Under Script Information, click the, +/- More Information link and under the, Perl Library Locations, select each point that begins with a, "/" and use those as your site-wide path to your perl libraries.
#2 Set the cron job
Cron Jobs are scheduled tasks. We're going to set a cron job to test for new messages every 5 minutes. Here's an example cron tab:
*/5 * * * * /usr/bin/perl /home/myaccount/cgi-bin/dada/plugins/scheduled_mailings.pl >/dev/null 2>&1
Where, /home/myaccount/cgi-bin/dada/plugins/scheduled_mailings.pl is the full path to the script we just configured.
If all this lib path changin' isn't up your alley, try this instead:
make NO changes in the plugin regarding the perl lib paths, but change the cronjob to something like this:
*/5 * * * * cd /home/myaccount/cgi-bin/dada/plugins; /usr/bin/perl ./scheduled_mailings.pl >/dev/null 2>&1
This should setup so the plugin is run from the, plugins directory and the Dada Mail and Perl libraries can be found, automatically. A lot easier.
Running Beatitude via the command line
Since this program is also command line tool, you can execute it via a command line. Running Beatitude without any flags will have it check if any schedules should be run, and mail messages that need to be mailed.
prompt>./scheduled_mailings.pl
I suggest before you do that, you test the scheduled_mailings.pl script.
Testing
You can pass the --test argument to scheduled_mailings.pl to make sure everything is workings as it should. The --test argument does not take any arguments. If everything is set up correctly, you'll get back a verbose message of the going's on of the script:
prompt>./scheduled_mailings.pl --test
------------------------------------------------------------------------
Running Schedule For: mytestlist
Current time is: June 26th 2003 - 5:25 pm
No schedules to run.
------------------------------------------------------------------------
In this example, Beatitude checked schedules to be run for the 'mytestlist' list, found none, and exited. If there is a schedule to run, the output my look like this:
------------------------------------------------------------------------
Running Schedule For: mytestlist
Current time is: June 26th 2003 - 5:33 pm
Examining Schedule: 'Justin's Test Schedule'
'Justin's Test Schedule' is active -
Schedule last checked: June 26th 2003 - 5:31 pm
Next mailing should be on: June 26th 2003 - 5:33 pm
'Justin's Test Schedule' scheduled to run now!
------------------------------------------------------------------------
Optional Fun Things
There's a slew of optional arguments you can give to this script:
--verbose
prompt>./scheduled_mailings.pl --verbose
passing the --verbose parameter is like giving this script some coffee. Similar to what you'd see if you ran the script using:
prompt>./scheduled_mailings.pl --test
But the scheduled mailings will actually get sent.
--log
If you pass a filename to the script it'll write a log entry that will look the same as what's outputted when you run with the --verbose flag.
If you don't want to pass the log each time, you can set a log in the $Plugin_Config-{Log}> variable.
--version
prompt>./scheduled_mailings.pl --version
WIll print out both the version of Beatitude and also of Dada Mail. Good for debugging. Looks like this:
Beatitude version: .1 Dada Mail version: 2.8.8
--list
./scheduled_mailings.pl --list myslistshortname
If you want to run schedules for only one list, you can pass the --list argument to scheduled_mailings.pl with a listshortname as its value.
Misc. Options
$Plugin_Config->{Plugin_URL}
Sometimes, the plugin has a hard time guessing what its own URL is. If this is happening, you can manually set the URL of the plugin in $Plugin_Config-{Plugin_URL}>
$Plugin_Config->{Allow_Manual_Run}
Allows you to invoke the plugin to check and send awaiting messages via a URL. See, "The Easy Way" cronjob setting up docs, above.
$Plugin_Config->{Manual_Run_Passcode}
Allows you to set a passcode if you want to allow manually running the plugin. See, "The Easy Way" cronjob setting up docs, above.
Debugging
Beatitude can be a bit difficult to set up, if you've never set up a similar script before. Here's a few things I do, to make sure a Beatitude install is working correctly:
First off, I install Beatitude, using the directions above.
Then, I'll make a test list, so if something goes wrong, no one will be affected. I won't add any subscribers, since it won't be necessary. Any test messages I send out will go to the list owner (me).
I'll then create a new schedule to send a message, every minute and repeat that schedule, indefinitely.
Then, I'll connect to the server via ssh, and run the command to run Beatitude, exactly as I would type the command in the crontab - except perhaps I'll put that --verbose flag on there, so I can see what's happening.
It takes a minute for the first message to be sent, and after that, every minute, if I run the command, I'll get a mailing. This will let me know that the schedules are firing correctly, and that I have the correct command to run Beatitude.
If that's working, I'll set the cronjob - and have it run every five minutes or so. I'll get some coffee.
I'll come back and if I have a few messages that I didn't send, I'll know the cronjob did its job.
FAQs
I keep getting, 'permission denied' errors, what's wrong?
It's very possible that Beatitude can't read your subscription database or the list settings database. This is because Dada Mail may be running under the webserver's username, usually, nobody, and not what Beatitude is running under, usually your account username.
You'll need to do a few things:
Change the permissions of the list subscription and settings databases
You'll most likely need to change the permissions of these files to, '777'. PlainText subscription databases have the format of listshortname.list and are usually located where you set the $FILES Config file variable. .List settings Databases have the format of mj-listshortname and are usually located in the same location.
Change the $FILE_CHMOD variable
So you don't need to change the permissions of the list files for every new list you create, set the $FILE_CMOD Config variable to 0777:
$FILE_CHMOD = 0777;
Notice there are no quotes around 0777.
I found a bug in this program, what do I do?
Report it to the bug tracker:
http://sourceforge.net/tracker/?group_id=13002&atid=113002
What's up with the name, Beatitude?
Beatitude, in a historical context, refers to one of the eight sayings the Christian prophet, Jesus is believed to have said on the Sermon on the Mount. Each saying starts with, "Blessed are the..." - a similar saying over and over again, much like sending a similar message again and again
It also means, "a state of supreme happiness".
But to me, I think of Beatitude as almost a shorthand for, Beat Attitude; the Beat Generation being a group of writers whose inner circle included Jack Kerouac, Allen Ginsberg, William Bourroughs, Gregory Corso and many more.
To Kerouac, "Beat" -- a shorthand term for "beatitude" and the idea that the downtrodden are saintly -- was not about politics but about spirituality and art. -Douglas Brinkley
A modern Beatitude would be Ginsberg's Please Master, found in the book, Fall of America.
The Beat Generation attempted to communicate the thoughts, ideas and adventures of their normal lives. I can only hope that communication with my Beatitude will be a tenth that incredible.
My personal bookshelf is overflowing with books from the Beat Generation authors and one reason I moved to Boulder, CO, and then Denver, CO was because of the Denver adventures of Sal Paradise and Dean Moriarty in On The Road and to be close to the Jack Kerouac School of Disembodied Poets in Boulder, CO.
COPYRIGHT
Copyright (c) 1999 - 2014 Justin Simoni http://justinsimoni.com All rights reserved.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.