Lyris User's Guide
[previous] [next] [contents]
Parental Approval of Subscriptions
Table of Contents
· Introduction
· Email Commands
· Web Interface for Users
· Server Administrator
· Site Administrator
· List Administrator
· Other Topics
· Add-On Packages
· · NT Authentication Option
· · Lyris List Manager ODBC Driver
· · Random Document Responder
· · Parental Approval of Subscriptions
· · Allowing Users to Subscribe from a Web Form
· · The Apache Web Server
· Installing and Upgrading
· Appendix
· Frequently Asked Questions

Parental Approval of Subscriptions

The Lyris List Manager extension "pap" performs the task of allowing parental approval of subscription requests. The idea is that a child requests to join a mailing list, but is required to give their parent's email address so that the parent can approve of the subscription. The child fills out a web form giving their email address and their parent's email address. This extension this sends an approval request to the parent and a notification to the child. When the parent approves (or denies) the approval request, the child's subscription is changed accordingly, and the child receives an acknowledgement.

This documentation page explains how to install this extension on your server. This is a good example of an extension script and the kind of functions you can perform with one. This extension is available at no cost.

Download and Extract the files

First, you will need to obtain the rdoc extension, by downloading pap.zip from http://www.lyris.com/down/scripts.html

The pap extension files are stored in this ZIP archive, but work equally well on Unix. Use Winzip or Pkunzip or 'unzip' (if you are on Unix) to extract the files out of this archive into a directory, from which you will run your extensions. On Windows, we recommend C:\lyris\ext while on Unix, we recommend /opt/lyris/ext

Copy the file "lyris.plc" into this directory. If you have configured your Lyris List Manager installation to use your web server, the "lyris.plc" file will be in the CGI-BIN directory (or SCRIPTS directory, if you are using IIS). If you are using the Apache web server installed with Lyris List Manager, this file will be found in the lib directory under Apache.

If you are on Windows, and you used a directory other than c:\lyris\ext you will need to edit rdoc.bat to reflect the directory path you used. Also, if your installation of Perl is not located in c:\perl5 you will also need to edit this file.

If you are on Unix, be sure to do a "chmod 700 /opt/lyris/ext/pap.pl" to make the file executable.

Next, you will need to copy the "papsub.pl" script to your CGI-BIN directory (or SCRIPTS, if you are using IIS). If you are using Unix, be sure to run "chmod 777 papsub.pl" to make the file executable.

Finally, copy the "papsub.html" file to an HTML document directory on your web site. This is an example of the web subscription form that you can modify, and if you like, embed in another web page.

Set the Extensions Directory

Go to the Server Config page of the Server Admin menu, and locate the "Extensions Directory" option, which is in the "Programming Extensions" group on the Server Config page.

Set this setting to be the directory where you placed the files from the rdoc archive file. If you followed our recommendations for default directories, you would type "c:\lyris\ext\" on Windows, or "/opt/lyris/ext/" on Unix. Remember to include the final slash, or your extensions will not work.

Save your new Server Config settings.

Edit the Subscription Form

Pull up the papsub.html file in a text editor. You will need to change the following pieces of information in the form, so that it works on your site.

Where you see the text:

    <input type=hidden name=goto_url value="http://xxxxx.xxxxxx.com/">

Change the value="" portion to be a URL that you want the subscriber sent to after they fill out the form.

Where you see the text:

    <input type=hidden name=goto_text value="Click here to return to xxxxx">

Change the value="" portion to be the text that you want the subscriber to see after they fill out the form.

Where you see the text:

    <INPUT TYPE="hidden" NAME="list" VALUE="signup-list1@xxxxx.xxxx.com">

Change the value="" portion to be "signup-listname@youserver.com", that is to say, to be the word "signup-" prepended to the list address of the mailing list in question.

Note: You have the option of having this script offer check-boxes to let the subscriber choose what lists they want to join and to join several lists if they like. If you want to do this, remove the line above, and replace it with lines like this:

    <input type="checkbox" name="list" Value="signup-list1@xxxxx.xxxx.com">List One<br>

Write a line like this one for each list that the subscriber can consider joining.

Create a Template User

Go to the Members page of your web interface, and create a member with the following settings:

    Email address: template@template.com

    Name: template

    Status: confirm - awaiting confirmation from user

All new members of this mailing list, which use the parent approval script, will be copied from this "template" member. You should set any other settings that you think are appropriate.

Save the member.

Create the Documents

Use the web interface to go into the List Administrator menu and choose to create a new document.

You will need to create three documents for this extension to work correctly.

First, you will need to have a "welcome" document that the person will receive when the subscription is approved by the parent. You define the document in the list's "list info" page.

Next, you will need a "your subscription is pending" document, which tells the child that the parent must now approve the subscription.

Here is an example of what we filled in for our sample document:

    Name: list1-pending

    Language: English

    Type: RESPOND

    Title: Your subscription request was received

    Body: Your request to join the '$subst('Member.List')' mailing list has been received.

    An approval request has been sent to '$subst('Member.Additional')'.

    When the approval for your subscription is received, you will become a full member of the mailing list.

    -----------------------------

The mail merge codes $subst('Member.List') and $subst('Member.Additional') may be used. The $subst('Member.Additional') refers to the parent's email address and is saved in the member's "Additional" field for archival purposes.

Finally, you will need a "your approval is needed" document, which is sent to the parent.

Here is an example of what we filled in for our sample document:

    Name: list1-need-app

    Language: English

    Type: RESPOND

    Title: Your approval is requested
    Body: The email address '$subst('Member.EmailAddr')' has been entered for a subscription to the '$subst('Member.List')' mailing list.

    This new subscription requires your approval before it will become active.

    To approve of the subscription, simply reply to this message.

    Make sure that your message is addressed to

    lyris-confirm-$subst('Member.MemberID')-@$subst('Site.Hostname')

    You will receive notification that your confirmation has been approved.

    If you do not want to approve the subscription, do nothing. The email address will be automatically removed. If you want to immediately reject the subscription, forward this message to

    leave-$subst('Member.List')-$subst('Member.MemberID')-@$subst('Site.Hostname') .

    -----------------------------

The mail merge codes $subst('Member.List'), $subst('Member.EmailAddr'), $subst('Member.List'), $subst('Member.MemberID') and @$subst('Site.Hostname') may be used.

Create the Autoresponder

From the List Administrator menu, choose the auto-responders menu and then choose to create an autoresponder.

In the create autoresponder page, put the email address you want the autoresponder to use in "email address". We recommend that you use the word "signup-listname" as the email address.

In the "response" field, choose "nothing".

In the "run a program before" field, enter text that looks like this:

    pap.bat $MESSAGEID list1 lyris@yourdomain.com yourdomain.com english list1-pending list1-need-app

You will need to change the items on the command line to fit your needs. The parameters are:

    pap.bat: this is the program name to run. On Unix, this should be "rdoc.pl"

    $MESSAGEID: this is required, in order for the script to know what incoming message to look at

    list1: this is the name of the mailing list under which the documents have been created.

    lyris@yourdomain.com: this is the email address that will be used in the From: field when the extension sends a "your subscription is pending" message to the child.

    yourdomain.com: this is the hostname of your Lyris List Manager, and is used to build the From: address of the parental approval request.

    english: the language that was used to create the documents.

    list1-pending: the name of the document to send to the child.

    list1-need-app: the name of the document to send to the parent.

Save the autoresponder.

Test the Autoresponder

Use your email program to send an email message to the autoresponder. Put the parent's email address in the Subject line of your message. For example, your message might look like this:

    From: me@somewhere.com
    To: signup-list1@mydomain.com
    Subject: myparent@elsewhere.com

You should receive a document in a few moments. If the extension does not work correctly, run Lyris List Manager in the foreground, with debugging information displayed, with the command "lyris start debug". This will show you information when the extension is run, and what the problem is.

Test the Web Signup Form

Next, use your web browser to display the papsub.html document. Fill out the forms, submit it, and test if it works.

Other pages which link to this page:
  • Add-On Packages
  • Page 492 of 629