WordPress Remote Poster v.03
—————————————————–
Script developed by and copyright by Ask-A-Geek.com. Ask-A-Geek.com assumes no liability and makes no claim of guarantee regarding the use of this script.

License: Free for individuals, corporations and government agencies. Do not reproduce or redistribute this script without written permission from Ask-A-Geek.com
—————————————————–

At a glance
————————————
1 ) About
2 ) Version Release Date
3 ) Requirements
4 ) How to install on a server
5 ) How to configure the script
6 ) List of shortcodes
7 ) How to use shortcodes
8 ) Examples of how to use the shortcodes
9 ) Questions? Problems? Love it?

1) About
————————————
WordPress Remote Poster allows users to post to their WordPress blogs by sending an email to themselves. The WordPress Remote Poster reads the emails, pulls out the neccessary information and feeds it to WordPress automatically allowing a user to post to their blog from anywhere they have an internet connection. It finishes up by removing the emails from the server.

What makes this script different from other WordPress posters is its nature of security and integrity. In no way does WordPress Remote Poster interact with the database used to host the blog data. It navigates the forms as a user would and posts the information as if it were done manually. This ensures the database is secure and the original WordPress filters monitor the data before it is submitted.

This script is written in Perl, not PHP. It was not designed to be an add-on or widget for WordPress. It is a standalone application.

2) Version Release date
————————————
March 25, 2011

3) Requirements
————————————
A server running Perl.
A server having the following Perl modules: WWW::Mechanize, Mail::POP3Client

4) How to install on a server
————————————
1) Transfer the aagwpposter.pl file as ASCII to your web server (make sure it is transferred into a location that can run Perl scripts such as a CGI-BIN).

2) Change the permissions (CHMOD) of the aagwpposter.pl file to 755.

5) How to configure the script
————————————
1) Open the aagwpposter.pl file in a text editor (such as Notepad)
2) Scroll down to the configuration section that is near the top (as shown below)
################################################
# Change your settings below
################################################
#######
# Email/Server settings
#######
my $email_user = ‘secretemail@domain.com’;
my $email_pass = ‘password’;
my $email_server = ‘mail.domain.com’;
my $file_backup = ‘/home/username/public_html/WPbackuplocation’;
my $tag_check = ’1′;
my $server_backup = ’1′;

#######
# Verification email settings
#######
my $path_to_sendmail = ‘/usr/sbin/sendmail’;
my $email = ‘confirmation@email.com’;
my $from_email = ‘noreply@domain.com’;
my $subject = ‘WP post confirmation’;
my $verification = ’1′;

#######
# WordPress settings
#######
my $username = ‘user’;
my $password = ‘password’;
my $url_to_sign_on = ‘http://domain.com/wp-login.php’;
my $post_new = ‘http://domain.com/wp-admin/post-new.php’;

################################################
# Do not make any edits below this line
################################################

3) Edit the required fields as listed in the configuration section.
my $email_user: change this to the user name of the email address you will be sending the emails to so they can get posted. In most cases the username IS the email address itself, sometimes it’s just USER instead of USER@domain.com.

$email_pass: change this to the password of the email account listed above.

$email_server: Determine the email server your email address uses and write it here. Every email host is different.

$file_backup: This is the full folder path to the location on your server where you’ll have file backups saved. You can store files anywhere you have permissions on your server. Remember to create the folder name(s) after you edit the script so the script has a place to write the files!

$tag_check: The only values this can be are 0 or 1. Change it to 0 if you don’t want the script to check each post for proper use of shortcodes or 1 if you want it to make sure posts are written properly. This will ensure that you don’t miss a TITLE tag that makes the rest of the post post improperly. Most people should use 1 as the value.

$server_backup: The only values this can be are 0 or 1. Change it to 0 if you don’t want to record log files of each post the script adds to WordPress for you or 1 if you want backups made. This makes a backup copy of what you submitted in case something happens and it doesn’t post correctly you’ll still have the original post handy.

$path_to_sendmail: Change this to the path of sendmail on the server. The default is the standard location of sendmail but edit it if your location is different.

$email: Change this to the email address you want confirmation emails sent to after the script makes posts to WordPress.

$from_email: Change this to the FROM email address that will be used in the confirmation emails.

$subject: Change this to the email subject line of the confirmation email.

$verification: The only values this can be are 0 or 1. Change it to 0 if you don’t want to receive confirmation emails or 1 if you do.

$username: Change this to the WordPress username you want to post blogs with.

$password: Change this to the password of the WordPress account you want to post blogs with.

$url_to_sign_on: Because WordPress can be installed anywhere on a web server you need to change this to the login form (wp-login.php). In your browser navigate to the WordPress login area and copy and paste the location here. The page should end with wp-login.php.

$post_new: Because WordPress can be installed anywhere on a web server you need to change this to the location of the post-new.php page. In your browser, sign into WordPress and go to the page that allows you to create new posts. It should end with post-new.php. Copy that location directly into here.
4) Create the directory needed to make backups (as mentioned above under $server_backup). This is only necessary if you want to store backups.

6) List of shortcodes
————————————
Start of email [:start]
Post title: [:title]
Post tags: [:tags]
Post category: [:categories]
Post content: [:post]
Post status: [:status]
Post separator: ##########

7) How to use shortcodes
————————————
The only required shortcode is [:post]. The other ones are optional but what good is a blog post without that information? Everyone SHOULD use the [:start] tag but it is not required.

Each shortcode has to be used twice (except [:start] and the post separator) if it is used at all- once as a start tag and once as an end tag. That is to say you wrap the shortcode around the text you are referencing. The start tag and the end tag are identical.
IE: [:title]Hello world, WordPress Remote Poster made this![:title]

The shortcode start and end tags can be on separate lines. For example, the code below will process smoothly:
[:title]Hello world!
Nice to meet you![:title]

You may not nest shortcodes as the results will be entertaining to say the least. For example, the code below should not be used:
[:title] Hello world! [:tags]hello, world[:tags] [:title]

The [:start] tag is special as it tells the script when to start looking at the content of the email. This is to prevent any free email client from placing advertisement text at the top of your emails. It is used only once per email and it should be the very, very top of everything.

There is no [:end] tag because the only data it cares about are within the shortcodes listed above. Once the last [:post] is processed no advertisement text will be included at the end of the post.

The [:status] tag allows you to define how the post gets sent to WordPress. If this tag is left off or is anything BUT [:status]publish[:publish] the post will be posted in DRAFT mode. You must specifically call on PUBLISH for it to go live.

The ########## separator is used when you want to write more than one blog post per email. Just separate each post with the separator and the script will post them separately. You can make as many posts in a single email as you’d like.

Shortcodes don’t have to appear in any order with exception of the [:start] tag. If that is used it has to be at the top or everything above it will get ignored. This means you can use [:post] to add all the content of the blog posting before you outline what the title and tags will be.

** The [:categories] is special and takes a little more human intervention to work. You can only post to 1 category per post (future updates may fix this) and you need to know the category ID number. This is NOT the name of the category itself. You will need to look at the HTML source code of the page where you make new posts to see what number is associated with what category name. The below source code is from Ask-A-Geek.com to show an example.
<ul>
<li id=”category-3″ class=”popular-category”><label class=”selectit”>
<input id=”in-category-3″ type=”checkbox” name=”post_category[]” value=”3″ /> Ask-A-Geek Exclusives</label></li>
</ul>
You will search the HTML for the title of one of your categories, in this example I knew Ask-A-Geek Exclusives what a category name so I searched for that. You see an <input id=”" type=”text” name=”" value=”3″ />

8 ) Examples of how to use the shortcodes
————————————
Example 1: email containing one post
[:start]
[:title]Hello world![:title]
[:tags]hello, world, first post, yay![:tags]
[:categories]1[:categories]
[:status]publish[:publish]
[:post]
this is the coolest thing ever
I posted this with WordPress Remote Poster from Ask-A-Geek.com
[:post]

Example 2: email containing more than one post (notice the start tag used only for the first post)
[:start]
[:title]Hello world![:title]
[:tags]hello, world, first post, yay![:tags]
[:categories]1[:categories]
[:status]publish[:publish]
[:post]
this is the coolest thing ever
I posted this with WordPress Remote Poster from Ask-A-Geek.com
[:post]

##########

[:title]Hello world 2[:title]
[:tags]hello, world, first post, yay![:tags]
[:categories]1[:categories]
[:status]publish[:publish]
[:post]
this is the coolest thing ever
I posted this with WordPress Remote Poster from Ask-A-Geek.com
[:post]

Example 3: basic post with the tags in random order
[:start]
[:status]publish[:publish]
[:tags]hello, world, first post, yay![:tags]
[:categories]1[:categories]
[:post]
this is the coolest thing ever
I posted this with WordPress Remote Poster from Ask-A-Geek.com
[:post]
[:title]Hello world 2[:title]

Example 4: not all shortcodes used
[:start]
[:title]Hello world![:title]
[:post]
this is the coolest thing ever
I posted this with WordPress Remote Poster from Ask-A-Geek.com
[:post]

9) Questions? Problems? Love it?
————————————
Please visit the WordPress Remote Poster page at [here] to ask any questions you may have or just post how much you love it! If you have ideas on how to improve it, please post them there as well.