"Email This Entry"

Version 1.0 - Beta 2

January 28, 2003

Written by Rick Ellis

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

CHANGE LOG

V 1.0 beta 1
 - Public beta release
 
V 1.0 beta 2
 - Changed how the script recognizes where the message body begins.

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

OVERVIEW

 This script allows you to email weblog entries to your own email account
 and have pMachine get them and put them in your database as if you had
 posted them via the pMachine control panel.

 The basic process of emailing entries is this:

 1.  You send an email to yourself (or any email account you choose).

 2.  The "mailserver.php" script gathers the email and put it into your 
     pMachine database.
    
        
 NOTE: This script does not handle image attachments yet.  Only plain-text
 emails.

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

INSTALLATION

- Open the file called "mailserver.php" with a text editor. 

  In the top portion of this file you will see some configuration 
  variables.  Set these variables to correspond to the POP3 email 
  account you want the script to access.

- Upload the following two files to your main control panel ("pm") 
  directory.

  mailserver.php
  mailserverlog.txt

- Set permissions (chmod) on "mailserverlog.txt" to 666.


OPTIONAL

- If you want the email routine to happen automatically, upload
  "mail_autocheck.php" into your "scripts" directory.
  
  NOTE: Do not place "mail_autocheck.php" in the scripts directory 
  until you are certain the email submission routine is working correctly.
  While you are setting it up you can trigger the email script manually 
  as described below.

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

USAGE

 You can either trigger the script manually by loading it with your web 
 browser, or you can have the script triggered automatically at a time 
 interval of your choice.

 It is recommended that you use the manual method at first while you are
 setting it up and testing it.  Once you are satisfied that it is working 
 correctly you can switch it to automatic by uploading the file called
 "mail_autocheck.php" into your "scripts" directory.

 For manual usage, point your browser to "mailserver.php".
 The script will attempt to access your email account.  If your settings
 are correct, the script will tell you so.  You can access the script
 even if you don't have pending emails and it will run through the
 routine.  This is a good way to test your settings.
 If you have emails ready to be submitted, the script will gather 
 them and do so.

 If you are triggering the script automatically, it will only 
 happen when a visitor loads any one of your pMachine-powered pages 
 after the time interval you have specified has lapsed.  Scripts 
 generally can not run by themselves (unless your server allows cron jobs),
 so to get around this, your visitors will trigger the script for you
 without realizing it.  You are advised not to set the time interval
 too frequently since it will briefly slow down the page load for each 
 visitor that triggers the script while your email account is accessed.

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

EMAIL FORMATTING
  
 There are two items that emails must contain in order for the script
 to treat them as valid weblog submissions.

 1.  A subject prefix.  

 2.  Your control panel username/password.

SUBJECT PREFIX:

 The subject of your email will become the title of your weblog entry.
 In order for the script to know which emails should be turned into 
 weblog entries, the subject line must contain a prefix.  By default,
 the prefix is "POST:" (without quotes). You can change this prefix in
 the script preferences. 

 For example, if the title of your weblog entry is "Lunch at McDonalds",
 you will use the following subject line in your email: 
 
 POST: Lunch at McDonalds.

USERNAME/PASSWORD:

 On the very first line of your email messages you must put your 
 pMachine username and password, separated by a colon.

 For example, if your username is "admin" and your password is "admin",
 the first line of your emails will look like this:

 admin:admin
  
-------------------------------------------------------------------------
  
OPTIONS

 By default, the text of your email will be placed in the "body" field of
 the default weblog you use.

 You can, however, specify where you want the text to go (blurb, more, etc.)
 by wrapping the text between any of the following tags:
  
    <blurb></blurb>
    <body></body>
    <more></more>
    <custom1></custom1>
    <custom2></custom2>
    <custom3></custom2>

 You can also specify the weblog by putting the name between these tags:
  
    <weblog></weblog>
    
 As well as the category:
    
    <category></category>

 You can also make set the entry status to "closed".
     
    <status>closed</status>
 
-------------------------------------------------------------------------
 
IMPORTANT NOTE:

 Email programs tend to add line breaks every x number of characters
 so that the lines wrap evenly, whereas when you submit entries
 using your browser, the line breaks only happen if you specifically
 choose to place them somewhere.  You might have to change your email
 preferences so that your text does not hard-wrap.
 
 -------------------------------------------------------------------------

TO-DO

- Add attachment handling so that you can attach images for placement 
  in your entries.
   
- Add a timeout feature so that the email server is only attempted to be
  contacted for a user-specified amount of time.
  
- Add more secure authentication
