How does it work?

Postcard Direct works by MIME encoding any images, midi, flash etc. This means everything that is needed to display the postcard is contained in the mail body.

PD also works with two other modes:

Web mail - Most web mail sites can't/won't handle embedded images in the email, so this mode references the images from the website the postcard was sent. Note that Yahoo Mail and Hotmail, in particular, change their interfaces reasonably regularly, so if the direct method works one day, it may not the next.

Traditional mode - Works like all other postcard programs, ie: stores the card on your webserver and mails out a ticket to the recipient.

Quick Install Guide

If you used the Auto-installer, you should have an operational postcard system ready to go.

If you have done a manual install, make sure the permissions are set correctly.

Once you have verfied that you have a working system by sending a test card from the PD example page, ie: http://www.yoursite.com/pd/postcards.html, you would then do:

Access the admin interface, eg: http://www.yoursite.com/cgi-bin/pd/pdadmin.cgi and set an initial username/password.

Edit the configuration file to change any defaults to your own preferences.

Edit the form and design templates to suit your website.

Create thumbnail pages that links to pd.cgi. See operation modes for more details.

Definitions

The following definitions are a used to clarify terms used in the documentation.

Full URL

The complete URL for your site, comprising the server name and the file path, eg: http://www.ginini.com.au/pd/images/bird.gif/

Short URL

A file path portion of the full URL. For example, for the full URLhttp://www.ginini.com.au/pd/images/bird.gif the short URL would be /pd/images/bird.gif

Full directory path

When you specify a URL of a file, the web server it is coming from will know the full directory path on the Operating System where to retrieve the file from. For example, if I have a short URL of /pd/midi the real location (full
directory path) could be something like /home/ginini/htdocs/postcard-direct/midi
The actual path will vary from webserver to webserver.

The full directory path is displayed in the diagnostics section if an error occurs.

Installing

Auto Installer

You can try the auto-installer, if you don't want to manually install the files.

Extracting

The source is contained in a gzip tar file or ZIP file.

To unpack the gzip tar file, type:

gzip -dc postcard-direct.tar.gz | tar xvf -

To unzip the ZIP file, type:

unzip postcard-direct.zip

or use best to WinZip. Note that WinZip will handle both tar.gz and zip files.

This will create two top level directories:pd - where the images, midi and html files exist.cgi-bin/pd - where the scripts, admin, configuration and template files exist.

Copy the pd directory to the directory where your web documents exist.
Copy the pd directory from cgi-bin/pd to the directory where your CGI scripts exist. In most cases this will be your cgi-bin directory. Other locations maybe cgi-local or scripts.

IMPORTANT - When you FTP the files to your web server, make sure that only the graphics and midi files are transfered in binary mode, all other files should be transfered in ASCII mode. If you fail to do this, it will most
likely cause the script to fail. Also note that the Auto setting on FTP clients such as WS-FTP is not always reliable.

Permissions

There are two sets of permissions that need to be set depending on how you are going to manage PD.

If you are going to administer PD via the pdadmin menu interface, you will need to set the following permissions:

If you are not familar with what the numbers mean, the following table will help:

Mode

Permission

Description

777

rwxrwxrwx

Read/Write/Execute for owner, group and other.

755

rwxr-xr-x

Read/Write/Execute for owner. Read/Execute for group and other.

666

rw-rw-rw-

Read/Write for owner, group and other.

644

rw-r--r--

Read/Write for owner. Read for group and other.

Where a * is specified, it means all files in that directory.

For Windows servers, 777 or 666 is roughly equivalent to read/write access for everyone, 755 is not applicable and 644 is roughly equivalent to write permission for the owner and read for everyone. Usually, only your ISP can change Windows permissions for you unless you have some type of Windows/Webserver admin interface.

Perl Locations

If your location of perl is not /usr/bin/perl then edit /cgi-bin/pd/pd.cgi, /cgi-bin/pd/pdadmin.cgi, /cgi-bin/pd/pdedit.cgi and /cgi-bin/pd/pdview.cgi to make sure the first line is the correct path for your perl location.

If you are installing on a Win/NT system, it depends which web server you are running as to whether the perl path is recognised. If you are running an Apache server, the path would be set to something like C:\perl\bin\perl.exe

On Microsoft IIS servers, CGI scripts are usually recognised by their extension. Generally this is set to be .cgi or .pl. If it is not set to .cgi you will need to rename the scripts to have the approprate extension.

Contains any cards that are due to be picked up and any cards stored to be sent at a later date.

configs

Contains the PD configuration file/s.

designs

Contains the design templates.

includes

Contains any include files for the postcard message.

lists

Contains list files, eg: badword list, midi list etc.

logs

Contains log file/s of postcards sent.

modules

Contains Perl modules

stylesheets

Contains CSS files

templates

Contains the various form and other templates.

Under /pd the following directories exist:

help

Contains the help files.

images

Contains sample images and icons.

midi

Contains midi files.

uploads

Contains any uploaded images/objects.

Configuration

Configuration File

In most cases, PD should work without any configuration changes. If you need to correct any paths or change any options, you can either edit the configuration via the admin interface, eg: http://www.yoursite.com/cgi-bin/pd/pdadmin.cgi or transfer the pdconfig.txt file to your PC, make the changes, and then transfer back to the webserver.

The Postcard Direct configuration is split into main and optional configuration sections. The main section contains the most common settings you would need to change.

Main Configuration Section

$site_url

Set this to the full URL for your site. Don't add any filenames to the path. You only need to set this if PD can't automatically determine your website name.

$document_root

If your web document root is not automatically determined, uncomment and set this the full directory path to the top level of your web documents. This directory path is where your home page would exist.

$url_alias

You only need to add this setting if your URL contains a ~, eg: http://www.yoursite.com/~peter

$pdurl

This is the short URL to where the PD images, help and midi files exist. Unless you are using non standard or an unusual location, this will always be /pd

$pdroot

This is the full path to $pdurl. There should be no need to change this setting.

$expire

By default, the admin login cookie will last for your browser session. If you want to put a time limit on it, uncomment this setting. +1h means expire after 1 hour.

$disable_uploads

If you want to allow image uploads, then you will have to set the value to 0 and increase the upload limit in $maxpost to the desired size.

Mail Options

$Subject

Set to a default subject line if none is specified/required.

$sendmail

Uncomment this line if you want the mail to be sent by sendmail. The path for sendmail is automatically determined by the pd.cgi script, or overridden if you set $sendmail_path

$sendmail_queue

You can speed up the operation of the script by using the sendmail mail queue. This is also a more reliable way to send mail as the mail will stay in a queue if there are any transient delivery problems or sendmail isn't running. The only tradeoff is that the mail will take longer to be delivered as it will sit in the queue until sendmail processes it at whatever interval is defined, usually 15 mins.

$sendmail_path

If your webserver has sendmail in an unusual location or if it uses a sendmail alternative like qmail, uncomment and set this path. This will override the automatic check for the sendmail path.

$smtp_server

If you don't have sendmail on your server, set this to the Hostname of your SMTP mailserver. Leave set to localhost if the server you run the script on handles mail, otherwise set to the full hostname of the server that handles your mail (generally your ISP mail server). If your webserver is running on a Windows server, this is you will need to use this setting.

Admin Interface Section

$admin_referers

Set this to a comma separated list of all the domain names that can call the pdadmin.cgi script. You should also include the IP address/es if you find the domain names are recognised. This means you will need to create a page on your website with a link to pdadmin.cgi in order to have the correct referer set. In most instances you probably don't want to do this.

$expire

Uncomment this setting if you want to have an expiry time on the admin login/session. If it is commented the admin session last until the browser is exited.

Anti-Leech Section

$AntiLeech

Set to 1 to turn anti-leech functions on, 0 to turn off.

$referers

Set this to a comma separated list of all the domain names that can call the pd.cgi script. You should also include the IP address/es if you find the domain names are recognised.

Mail Sender Section

$sender_email

Set to the email address that the postcard will come from.

$sender_name

Set to the sender name of the postcard.

$reply_to

Set to an address if you want all replies to go to a single address.

$max_recipients

Set to the maximum number of recipients.

Requires Section

$require_sender_name

Require the sender of the postcard to fill out their name.

$require_receiver_name

Require the name of the recipient to be filled out.

$require_message

Require the postcard message to be filled out.

$strict_email_check

If this option is turned on additional checks are performed on the validity of the email address. If it is turned off, then the email address just has to be in a valid format.

$check_domain

This checks that the email address has a valid top level domain, eg: .com, .org, .au, .nz etc.

$allow_html

If this option is turned on, HTML will be allowed to be used in the postcard messages. By default HTML tags are stripped from the message.

$check_bad_users

If this option is turned on, the email addresses of the sender and/or recipient are looked up in the badusers.txt file to see if they should be banned. This option is useful if you have a user is complaining of unwanted postcards.

$check_bad_words

If this option is turned on, the postcard message is checked against the list of banned words in the badwords.txt file.

$diag

If this option is turned on, diagnostic messages will be displayed on the error page.

$add_message_id

Your mail server will generate a Message ID, but in some circumstances, it may not generate one that complies to the suggested Internet standard. Setting the following option will make PD generate its own Message ID.

Language Options

$lang

Default language to use.

$title

This is the default page title that is used if none is specified.

Message Options

$max_message

Set to the maximum allowable size of the message. This is to prevent people abusing the script by trying to send out huge postcards.

$message_db

Location of the message database. This would not normally be changed.

Logging Options

$log_file

Set to a location where the log file will be written to.

$enable_logging

Set to 1 to enable logging or 0 to disable logging.

Remote Images Section

$remote_sites

Set this to the file that contains a list of all sites that you can specify a remote postcard image from.

$cache_expiry

Set this to the number of days that an image can exist in the cache before a new version is retrieved from the remote site.

$cache_age

Set this to the number of days that a cached image is stored before it is deleted. Set this value to be greater than $cache_expiry.

Image Upload Section

$disable_uploads

Set to 0 to enable and 1 to disable.

$maxpost

If you enable image uploads, you will need to increase this value from the default of 8KB.

$upload_dir

This is the directory to store uploaded images. Note that this directory needs to be writable by the webserver owner.

$upload_age

Age in days, that old uploaded images get deleted.

$upload_types

List of allowable upload types. Note that they are case insensitive.

Mode Options

$mode

This can be set to direct or traditional. If set to traditional, PD will operate like standard postcard systems, ie: send a ticket for the recipient to pick up their card. The following options are only used in traditional mode.

$postcard_dir

Location of where the postcards will be stored. By default, this is in the postcards directory where the PD HTML files exist.

$postcard_age

This is the maximum age in days to store a postcard on the server before it is deleted.

$future_card_age

This is the maximum age in days in the future that a card can be sent.

$receipt_subject

The subject line for read receipts. Only applicable for receipts sent in the 'traditional' mode.

Templates Section

$form

Template for the default input form.

$upload_form

Template for the image upload form.

$sent

Template for the confirmation page when the postcard is being sent.

$error

Template for any general error messages like missing cnofiguration files.

$input_error

Template for any invalid data entered in the postcard form.

$read_receipt

Template for read receipts for cards sent in 'traditional' mode.

$card-expired

Template for expired cards.

$stylesheet

Default Stylesheet (CSS) to use for postcards.

Templates

There are templates to control the entire output of Postcard Direct. This means that no perl code needs to be changed in order to customise the web pages.

The templates consist of HTML code with special tags embedded in them. The special tags have a <pd_ prefix. You can also use special variables that a surrounded by percent signs %, for example:

%TITLE%

or

<pd_title>

These variables/tags are expanded to their appropriate value when the pd.cgi reads the template.

The reason that two methods are given is:

Personal preference. You may decide that using special tags is easier to type and read, or visa-versa.

Some HTML editors don't like %VARIABLES% or will change the formatting of them, in which case, using the special tags may help.

NOTE - You can mix both types of variables/tags if you desire.

Forms

There are a number of form templates which control the look of the postcard form where the user enters their message and who they are sending the postcard to. The following form templates are pre-defined:

Multi-Lingual Support

English is the default language, although this can be changed in the configuration file.

You specify a non default language by using the lang parameter. For example:

pd.cgi?lang=br;image=/pd/images/photo.jpg

Each language is represented by its two letter ISO639 code. If no specific ISO639 code exists for a language, use the appropriate two letter country code.

To add support for a new language, you need to edit/create the following:

/cgi-bin/pd/admin/messages.txt

This file contains a list of all the messages generated by the script. Add a translation for each message type.

/cgi-bin/pd/admin/languages.txt

This file contains a list of all supported languages. Add the two letter language code and description to the file.

/cgi-bin/pd/modules/pddates.pm

This file contains a list of the short month names. It is used in the form-dates.html template

/cgi-bin/pd/modules/charsets.pm

This file contains any charsets required for a particular language. The default is ISO-8859-1.

/cgi-bin/pd/templates/language

Create a new directory for the HTML templates and copy/translate existing templates.

/cgi-bin/pd/lists/language

Create a new directory for the lists and copy/translate existing lists.

/cgi-bin/pd/designs/language

Create a new directory for the postcard designs and either create new postcard designs or copy in existing designs.

/pd/help/language/help.html

Create a new directory and translate an existing help file.

Log File

Postcard Direct writes an entry in a log file everytime a postcard is sent out (if logging is enabled). The Admin Menu has an option to view a summary of the log entries.

The format of the logfile is:

Field

Description

Date

Date in YYYY-MM-DD format. Y2K complient

Time

Time the postcard was sent in HH:MM format

Method

Sending method. Either html, web or plain

Design

The postcard design that was used

Image URL

Postcard image

MIDI

Name of midi file

Object

Name of the object file

Remote Host

Hostname where the request came from

Subject

Postcard subject

Sender email

Email address of the sender

Sender name

Name of the sender

Recipient email

Email address of the recipient

Recipient name

Name of the recipient

Send Date

The date the card has/will be sent

BCC

BCC option specified

Send Copy

Copy was sent to the sender

Field 1

Free form field

Field 2

Free form field

Field 3

Free form field

Field 4

Free form field

Field 5

Free form field

Field 6

Free form field

Message

Postcard message

Testing

If you have a command line access on your web server, you can check that the syntax of the scripts is correct by typing:

perl -c pd.cgi

If no errors are reported, try running the script using:

./pd.cgi

If everything is correct, it will spit out some HTML code saying it requires an image URL.

Once you reach this point, try invoking it from your web browser using the sample image, eg:

http://www.yoursite.com/cgi-bin/pd/pd.cgi?image=/pd/images/photo.jpg

Modes of Operation

General

You can use images that are stored anywhere on your webserver that is viewable. They do not need to be in any particular directory. The most common form of operation is to just specify the path to the image for the postcard. For example:

Make sure that when you specify the URL for the postcard image you use the full document path from your web root ie: has a leading /. For example, use a path like /postcards/images/photo.jpg rather than
../images/photo.jpg

Parameters

The full list of parameters available are:

Parameter

Description

Example

image

URL to a postcard image.

image=/pd/images/photo.jpg

object

URL to a postcard object.

object=/objects/cartoon.swf

title

Title of the postcard. Uses the default if none specified.

title=Some+Postcard+Title

subject

Subject of the postcard. Uses the default if specified in the configuration file.

title=Some+Subject

include

Includes the text from the specified include file.

include=pd.txt

config

Name of alternative configuration file. Uses the default if none specified.

config=myconfig

form

Name of postcard form to display. Uses the default if none specified.

form=form-java.txt

stylename

Name of stylesheet to use. Uses the default if none specified.

stylename=newstyle.css

lang

Language to use. Uses the default if none specified.

lang=de

upload

Invoke the image upload form.

upload=yes

Thumbnails

The most common way of setting up a Postcard site is to have a page of thumbnail images, with the postcard using the full sized image. For example, assume the following directories:

<a href="/cgi-bin/pd/pd.cgi?image=/postcards/large/photo.jpg"><img src="/postcards/th/photo.jpg" border="0" alt="Click to send as a postcard"></a>

Flash Postcards

When specifying a flash object, use the object parameter, and specify the form template for flash postcards, for example:

/cgi-bin/pd/pd.cgi?object=/objects/movie.swf;form=form-flash.txt

By default, the form-flash.txt template will use the flash.txt design template. If you want to change this, edit the form template, and change the line:

<input type="hidden" name="design" value="flash.txt">

To point to the desired design template. Note that the sending method is set to traditional via a hidden field. Embedded flash objects in a email is unreliable as lot of mail clients don't support it, or their security restrictions prevent viewing it.

Java Postcards

To specify a java postcard, specify the java form template, for example:

/cgi-bin/pd/pd.cgi?image=/images/photo.jpg;form=form-java.txt

You will need to edit the form template and the java design template (defaults to java.txt) to insert whatever java applet you want to run.

Note that the Java form template has no sending options. It defaults to the web method. This is because you can't embed a java applet in an email message.

Multi-Lingual Postcards

If you want to set up postcards for different languages, use the lang parameter. For example:

/cgi-bin/pd/pd.cgi?image=/images/photo.jpg;lang=de

This example would use the German templates and German messages.

The default language is English, although this can be changed in the configuration file.

Traditional Postcards

If you want to offer a Postcard service that operates like all other postcard sites (ie: mails a ticket to the recipient for them to pick up their postcard), use the traditional form template. For example:

/cgi-bin/pd/pd.cgi?image=/images/photo.jpg;form=form-traditional.txt

You can edit the traditional.txt design template to modify the message sent to the recipient. You can make the traditional mode the default method by setting $Mode='traditional' in the configuration file.

If image uploads are enabled, then users can upload their own images for the postcard. These images are stored in the directory specified by $upload_dir.

$upload_age specifies the number of days an uploaded image is kept before it gets deleted.

Traditional Cards

/cgi-bin/pd/cards ($postcard_dir)

When a card is sent in "traditional" mode, a copy of the card is stored on the server for the recipient to "pick up". The card is stored in a file with a big long number with a .card extension, eg: 11691324960.629362261462123.card. Additionally, if a return receipt was requested, there will be a similarly named file with a .receipt extension.

$postcard_age - Number of days the stored card will be kept on the server before it is deleted.

Future Cards

/cgi-bin/pd/cards ($postcard_dir)

Any cards to be sent a a future date are stored as a file with a big long number and the .mail extension. A database of the cards to be sent is kept in .storecards.db

The future card files are only deleted when they are successfully sent.

Remote cached images

/cgi-bin/pd/cache ($cache_dir)

If remote images are allowed to be used for cards, they are downloaded and stored in a cache directory.

$cache_age is the maximum age in days before the cached image is deleted.

Administration Interface

Most operations such as editing templates and configuration files can be done through the administration interface. The administration interface is accessed through pdadmin.cgi. For example:

http://www.yoursite.com/cgi-bin/pd/pdadmin.cgi

If you forget your password, you can reset it by editing the /cgi-bin/pd/admin/auth file and deleting the second field, eg:

pdadmin:

Upgrading from version 5.x.x

The easiest way to upgrade is to save your modified templates and configuration file and do a fresh install.

Save a copy of your configuration file if you have made any changes to it (apart from setting the paths).

Save all your modified form and design templates.

Save any stored cards (if you operation PD in traditional mode). These will be stored in the /pd/postcards directory.

Remove your existing PD installation.

Install PD 6.

Edit the configuration file (/cgi-bin/pd/pdconfig.txt) and set any of the changes from the old version. Note that all the variable names are now in lowercase for consistency and easier editing, so don't cut and paste entries from a PD5 configuration file.

Put back any saved form/design templates. Remember that the form templates now have a .txt entension instead of .html (this is for consistancy reasons).

Put back any stored cards into /cgi-bin/pd/cards. Also ensure the permissions are set to 777 on each of the files.

Note that as there are additional fields in the log file, you will not be able to use the Usage Report with the logs from PD version 5.x.x.

Win/NT Notes

If you are running Postcard Direct on Win/NT systems, please note the following:

Some web servers require that CGI scripts have a particular file extention. You may have to rename pd.cgi to pd.pl or whatever extention the web server is set up to recognise.

The first line that has the location of perl (eg: #!C:\perl\bin\perl.exe) is only recognised on sites that run the Apache web server, otherwise it is ignored and is a function of the web server to be set up to recognise Perl
scripts.

It is much easier to use forward slashes instead of backslashes for pathnames. For example:

For the path C:\web\images\pic.jpg, you would assign it in Perl as either:

$Var="C:/web/images/pic.jpg";

or

$Var="C:\\web\\images\\pic.jpg";

or

$Var='C:\web\images\pic.jpg';

On most Win/NT systems, you won't have a sendmail running, in which case you need to use the SMTP mail option. If there is a mail server running on the same machine as the web server, you can leave the default localhost as the SMTP
server, otherwise specify the fully qualified hostname of your mail server.

Limitations

There are a some limitations using the Postcard Direct method of sending the postcard to the user via email as there is no set standard for handling HTML formatted mail. There shouldn't be a problem if the recipients mail client handles MIME
correctly.

The following limitations are known about:

A number of web mail sites (eg: Yahoo, Hotmail) will disable or strip certain tags. Yahoo will disable <BODY BACKGROUND=xxx> tags, along with any <OBJECT> and <APPLET> tags. You should
make sure you design your postcard with a text colour that will be visable on a white background. You can get around the problem by placing the entire page in a table with a background colour.

For some reason the Netscape mail client (for all versions up to 6.x) ignore embedded midi. It will work fine if the postcard was sent in web mode and the midi is referenced from the web site.

Due to continuing changes in a number of web mail interfaces, midi will not be able to be heard on sites like Hotmail and Yahoo mail.

Eudora mail client handles HTML mail in a very peculiar way, although the latest versions seem to work much better.