PostMan

Description

Using this plugin, you can post your entries via email and via mms. It uses cron to check a POP3 mailbox on a regular basis for new posts (note added by [[http://jystewart.net]])

Download files for Nucleus from http://www.nominaali.com/media/public/NP_PostMan_1.1_nucleus.zip
and for Blog:CMS from
http://www.nominaali.com/media/public/NP_PostMan_1.1_blogcms.zip
(only difference between versions is paragraph-function which already exists in Blog:CMS and thus can't be included)

Installation

1. Uninstall previous version of PostMan.  Unpack only one of the above  into your plugins directory.  There should be NP_PostMan.php in plugins directory and PEAR.php, mimeDecode.php, POP3.php and Socket.php under postman-directory (you can also update your previous version as files will get overwritten correctly).

2. Go to the 'manage plugins' section in Nucleus Admin, and install the plugin

3. Edit the plugin options. Make sure your default users media directory exists! Plugin will use each posting members directory as default (like your admin uses media/1 -directory). Directories should be writable. If you don't set default user, user-option with password **must** be used everytime you post.

4. Set up a cron tab for the NP_PostMan file. The URL that you need to put in the cron tab will look like 
"PathToNucleus/action.php?action=plugin&name=PostMan. " My settings in crontab are:
0,5,10,15,20,25,30,35,40,45,50,55 * * * * wget "www.mydomain.com/action.php?action=plugin&name=PostMan"
Edit your crontab logging in as user and typing ""crontab -e"". Above settings will run script every 5 minutes using wget. You can use also lynx-browser. 

Thats it!.

===Options===

The mail user name, password, URL (hostname) and port are mandatory.

Now enter the default username and password of the nucleus author. This will be used if no username and password is send along with the subject/body of the mail.

The publish straightaway option controls the publish status of the post. If this is set to yes, then the post will be published immediately otherwise it will be saved as a draft.

The should the mail contain a prefix option is a added safeguard. If you set this to yes and then give a prefix, then only those mails which contain that prefix will be posted. Note that in version 1.1 you can use same prefix either in body or in subject. That is to ensure all mms-messages can use prefix too.

The send output to browser controls debugging messages which may be displayed on the browser when you invoke the plugin. Set this to yes, if you are facing problems with the plugin. This will help you to see what is going on. I suggest you use plugin few times ""manually"" using output to browser and calling plugin from your browser. If everything works, then set to no and use cronjob / timer.

===Usage===

The email format is as described below :

	- The subject of the mail will be used as the title of the post.

	- The body is used as the main body of the post.

	- There can be an optional extended portion. If there is the keyword [more] anywhere in the body of the mail, anything that comes after it will be considered as an extended portion.

===Advanced Usage===

	- If the prefix option is set to yes and the prefix given as "nucleus:", then only emails with the subject looking like nucleus:A sample title, will be posted.

  - you can change default option-names in NP_PostMan.php, to convert them to different language etc.

	- If you want to give a user and password other than the default user and password, use the following syntax for the subject :
nucleus:A sample title[options]user=anand;password=smooth;

	- you must use a syntax similar to the above one. The equals-to symbol, semi-colons and the keywords should match what is described above. 

	- If you want to select a blog other than the default blog, use the following syntax for the subject :
nucleus:A sample title[options]blog=7;

		- The number above is the blogid of the blog you want to use.

	- If you want to select a category other than the default category, use the following syntax for the subject :
nucleus:A sample title[options]category=poems;

	- The short category name is used here NOT the id - like movies, not 1 or ""movies reviewed"".

===MMS===

  - If you need prefix in mms-messages (no subject when sent from phone for example), use first line of body to include options. If your prefix is ""nucleus:"" use:
    nucleus:This is my subject;Message itself along the picture.
    Above example uses default user and default category. **Note trailing ; after subject!!** 
    It is to ensure subject is separated from message-body if you use simple format. Neat feature if you use your mobilephone to write messages (every additional character is pain to write).
    Same options will work as above, thus you can use user, password etc.
  - Option -keyword should be after prefix and title, **again after ;**. This is important.  Example:
    PREFIX:Sample title;[options]user=ihra;password=mypassword;This is test message, blah, blah.

===FAQ===

Q:  Some characters are not shown correctly when posting with MMS

A: There is some problems with international characters (as some of them are sent via UTF-16 for example). If you can send your message with mms-2-mail some of these problems will get solved. You can use html-entities in your messages to prevent wrong conversion (mostly because UTF-16 characters show as two separate characters).

Q: Which fileformats are supported?

A: Nucleus supported pictures (png, jpg, gif) will get attached as inline images, all other files are posted as links in main article (pdf, word-files etc.). Even pgp-signature works fine.

Q: How about signature?

A: Standard signature separator (--) will be removed along everything after that. 

Q: Heard about encodings, about base64 or similar?

A: All mms-messages are encoded with base64 and PostMan will decode them correctly (pictures and text).

Q: My blog uses utf-8 characters, should they work?

A: Yes, script contains conversion function to format characters correctly - if needed, that is. 

Q: Sometimes my cronjob sends me errors about NP_PostMan, why?

A: Because script is run as a web-page, it depends on the workload and speed of your server. If there are many users in page doing database-calls, script will be slow and cron will not get feedback fast enough. Then it will give you error that it cannot connect to script. Most systems will have 30 seconds of waiting time for php-scripts. Note that this is mainly servers problem (and next run should be fine again).

===Examples===

	- Some sample **subject**s.

	- A sample title
		- This is the simplest usage. The whole subject will be used as the title and posted using the default username, password , default blog and default category.

	- prefix:A sample title
		- This has a prefix. The must contain prefix option must be turned on and the prefix should be given as prefix:

	- prefix:A sample title[options]user=anand;password=smooth;blog=7;category=poems;
		- This has everything in it. It will be posted with the username anand, password smooth in the blog with id 7 and under the category poems.

===Tricks===

	- Using this plugin, A submit story option ( as seen on sites like [[http://slashdot.org slashdot]] ) can be simulated. Just create a form for the user to fill in a title and body. Then in the action of the form, make it send a mail to the mail id you use. Remember to set the publish straightaway option to no. Better to save it as a draft which which you can authorise later on.

	- If you want to send html in your email, Instead of using the html option of your email client you can do another thing. Just send it as plain text but insert html manually. This is always the best option. Versions 0.3 or later will use html correctly.

	- If you must send HTML email, be carefull to edit the html source also so as to not include the complete HTML code ie the code for the head and meta tags and all such things. This plugin will post the complete HTML email as the body of the post. This will be displayed correctly but if you edit the message, you will be surprised at what you see :-) In outlook express, use the message source option to edit out the unnecessary tags. 

	- While editing a message posted as HTML email, if you make any changes and save it, nucleus will insert line breaks automatically and screw up the display. In such situations, before editing the post, set the convert line breaks option to no. Edit and then set the convert line breaks option back to yes.

===History===

NP_PostMan v0.1 (February 01, 2003)
	- Initial release
(after long period of development)
NP_PostMan v1.1 (October 28, 2004)
       - MMS support
       - html-support
       - supports MEDIADIR
       - body/subject prefix

===Notes===

	- Be carefull with the email id. It is better to set the must contain prefix option rather than wake up one day to find a spam mail has been posted on your site.
	- If you dont give a nucleus default username and password, then every mail must contain the username and password.
	- HTML email support should work (atleast bold, italic etc. which nucleus supports too). However, send your html-mail with html/enriched or html/text **not** as text/plain (no conversion of entities).
	- If the e-mail server resides on the same machine as your web server, use 127.0.0.1 to designate the POP server instead of the server's name.
