How do E-mail Digests work?

This digest feature depends on having a batch scheduling system that you can use. You will need to figure out a way to program your batch scheduling system to call the mail_digests.php program once an hour every hour of the day, every day of the week. If you cannot do that then there is no point using this feature!

How easy it is to do this step depends on whether you own your web server or it is hosted externally for you and how easily you can access the web server. If you own the server then presumably you are already familiar with the server operating system and the commands needed.

If you contract with a web host, access it remotely and you have never ventured beyond FTP to transmit files then you will have to connect via a terminal mode to issue the operating system commands to interact with your batch scheduling system.

If you do not have access to your server, or cannot setup some kind of local scheduling, see the method at the bottom of this page.

If your server is brought down you may have to go in manually and reprogram the crontab, so make a note of what you did, or store the commands in a file.

Usage notes

Most users who receive HTML digests using web based email programs like Yahoo! Mail will likely not see cascading style sheets applied to the HTML email unless frames are enabled, with a frame for the content of the email message. In the case of Yahoo! Mail, the message is displayed inside of a table <td> tag. Yahoo! Mail strips out <link> and related tags and appears to shove whatever content is between the <body> and the </body> tags of the email into the cell where the message appears. It all still works, just may not look as fancy (but still better than text).

You can use any theme you have installed on your board to theme the digest. By default it will use whatever theme the user has set (unless you have an overriding theme set in the ACP). If you want to overide both the board default and the user default (say you always want it to use subSilver, and your boards default is someething else) then you can set OVERIDE_THEME to true, and then set DIGEST_THEME to the theme (from the database) of the theme you want to use. Any images will be striped out of the theme, but colors sill stick and if the theme is well put together the colors will be at least close to the images that should be covering them. Note that the digest pulls the theme data from the database, NOT a css file.

Test to see if the digest user interface is working correctly. Via URL invoke digests.php in your phpBB root folder. Set it up so you receive a digest every hour.

Next, test to see if you can receive an email digest. Via ACP, run the "Mail Digests". You should see a text output indicating who received a digest, how many messages were sent and other information, that may or may not be usefull, along with a total count of the digests sent and some server date and time information. This will help in testing and resolving potential issues. Since this program is normally run automatically this information is not seen seen, but you can redirect output to a file if you wish (depending on how your server is configured). It may be an idea to turn logging on at this stage so that you have a record of what has been happening. If the digest was successfully sent it should appear in your email.

Next, follow the instructions below to setup batch scheduling and test it. Schedule yourself to receive a digest every hour. Hopefully it will pop into your mailbox in an hour of setting up your digest.

If you get errors when you run mail_digests.php you may need to change line 40 to show the absolute path to phpBB on your server (e.g. '/subfolder/local/home/mysite/mysite.com/') It is dependant on how the server is configured. On some servers it will work with the relative path set but on others it needs the absolute path (not sure why!)

Instructions for setting up a crontab (for Linux/Unix systems)

  1. If your web host allows straight telnet access, great. Log in. Skip to step 3.
  2. Most web hosts require that if you want a telnet access you have to use a secure telnet program, such as Secure Shell (SSH). Find out from your web host what you need to do to use SSH. My web host (successfulhosting.com) made me go through the following procedures:
    1. I had to provide identification by faxing them my driver's license. They then configured something on the server side giving me SSH permissions.
    2. I then had to download and configure SSH client software (I used Putty, which is free and available at www.chiark.greenend.org.uk).
    3. Using my SSH client I created an encryption key. I then used my host's Control Panel to provide the key to my web host.
    4. After some wailing and gnashing of teeth I got the thing to work. Eventually I connected successfully, entered my ID and password and got a server operating system prompt. From there I could issue operating system commands.
    This was not a trivial process. Elapsed time may take a day or two if you have not done it before.
  3. You will need a passing ability to use the Unix "vi" text editor to program your crontab job. Here is how I did it (do not send the quotes as part of the commands). Note that you need to first figure out the path to the PHP interpreter. I found it in /usr/local/bin but it may be somewhere else. You may have to ask your host's technical support department for the information. You also need the absolute path to the location where the mail_digests.php program is stored.
    1. From the command prompt, I entered the command "crontab -e" then Enter, which took me into a "vi" environment
    2. Typing "i" put me in the vi insert mode
    3. Very carefully I typed the following: 00 * * * * wget --delete-after http://yoursomain.com/phpBB2/mail_digests.php --http-user=??? --http-passwd=???
    4. I pressed the Escape key to get out of vi insert mode
    5. Typed ":wq" then Enter to get out of vi.
    6. To verify the job was scheduled I entered the command "crontab -l" then Enter.
    7. Logged out.

Note: If you want to set up an "Urgent" digest then follow the instructions above to add another crontab job but at point c. enter the following: */2 * * * * wget --delete-after http://yourdomain.com/phpBB2/mail_digests.php urgent --http-user=??? --http-passwd=??? This will have the effect of running this crontab job every two minutes (change the value 2 to whatever you consider appropriate).

Where the '???' parts at the end of the line you typed into vi are the username and password for the protected folder. If you want to do this without any protection, simply remove the last two paramaters completely.

For this feature to work a crontab must be programmed to run mail_digests.php once an hour for every hour of the day for every day of the week. The way I programmed this crontab, it will start every hour on the hour (the 00 above is the minute).

Guidance on setting up scheduled tasks for Windows 2000 and XP Servers

I don't have a Windows server, but it looks like if you download the phpAdsNew software at www.phpadsnew.com and read the Administrator's manual, pages 24-27 you should be able to figure it out. You will need to download wget for Windows, free software provided by GNU (), and create a batch file, and learn about how to tweak the Windows Task Manager. One user said that after wget was installed they created a batch file that looked like this:

wget -q -O - http://yourdomain.com/phpBB2/mail_digests.php?mode=direct&pass=????
exit

In the above where pass=???? replace the ???? with the password entered in Digests Configuration.

Quick & easy solution for those who do not have cron enabled

I am sure there are many out there who really wish to have a email digest working but the only barrier to overcome is the CRON nonsense. To save yourself all the trouble of setting up cron, simply follow what I have done.

  1. We all know by now that the trigger for sending out the digests is mail_digests.php, so as long as we can access this script at a fixed interval, the digest will work.
  2. One of the ways to do the above would be to set up cron or pseudocron or anything along that line. Heck, you could even reload that script manually every hour if you wanted to. But why not get others to do it for you?
  3. Sign up for any web-based uptime/site monitoring service and make them poll http://yourdomain.com/phpBB2/mail_digests.php EVERY HOUR (the fixed setting for this feature) to check for uptime. Upon trigger, your webhost will send out the digests. VOILA!
  4. Ok, I know there are security concerns over this but well, it works so those who are not that particular, go ahead and do so.
  5. For a list of free/paid uptime monitors, try www.vivante.com
  6. This method has been tested and proven to work, and in fact, it doubles up as a site monitor for you. Cool Stuff!