POSTIE Version 2 is (c) copyrighted 1997-8 and written by Andrew George Davison.

Permission is granted to freely use this program. The source may be used unmodified as part
of another program (or modified for platform porting purposes), but may not be modified and
used in another program unless that program be made available freely for non-commercial use.
Those interested in commercial exploitation of any of the source code contained herein should
contact the author.

	http://www.infradig.com
	mailto:andrew@infradig.com


POSTIE is a command-line mailer that handles multi-part MIME attachments, HTML mail, UUencode/decode,
WEB mail access, POP3 reading, SMTP and NNTP (Usenet) posting and list-server processing. It also does
inter-host mail relay...

  http://www.infradig.com/postie.zip


Experimental SSL enabled version...

  http://www.infradig.com/postiessl.zip


POSTIEX, a Windows OCX component, is available with limited POSTIE functionality (can send & receive)...

  http://www.infradig.com/postie.zip


It is portable and available in source from...

  http://www.infradig.com/postiesrc.zip


POSTIE comes with no guarantees, use at own risk in production environment. Test thoroughly in non-destructive
mode (i.e. without -rm option) to make sure it fulfills your need before commiting to use.


POSTIE doesn't have a GUI as it is not meant to be used directly as an e-mail client... it was designed for back-end
processing, to be used with schedulers, CGI, or to be exec() driven.


DON'T SEND THANKS, SEND MONEY!

While POSTIE is and will continue forever to be freeware, I happily accept small cash
donations in any major currency from grateful COMMERCIAL users. Please send cash or
travellers checks, not personal cheques (except in Australia) as there is very little
left over after the banks get their cut. Sorry but no credit cards either...

	Andrew G. Davison
	20 Leighton Street
	Wavell Heights
	Bribsane 4012
	Australia

People who pay can get the OCX source code as a bonus.

For commercial re-use of the source code in other products there is a one-off charge of US$250
with entitlement to all future updates but with no right to resell the source.

I also do contract work in this and other areas related to internetworking.


FREQUENT PROBLEMS:

Command-line options may not be abbreviated and are case-sensistive, so be careful! I get lots of mail
about this or that option not working and 90% of the time it's this. Also, double-quotes can be used
on any option that may legally contain spaces (filenames, email-addresses, text strings etc).

Be careful about default input! The other 90% of queries I get is people leaving off -nomsg or -msg:"text"
or -file:filename or <filename and complaing that POSTIE just sits there indefinitely and does nothing. If
you don't supply a message body POSTIE tries to read from standard-input to supply one. You can then
type in some text and terminate input in the usual manner, or you should more likely use one of the
options listed above.

Be careful using embedded double quotes, most shells require you to use \" to do so. For example...

    postie -s:"This is a \"test\" message".


There is also a known problem with sending attachments when the current working directory is
read-only or a Netware mounted drive. Just CD to your hard-drive and use full path names on
file specs.


USAGE:


For SMTP sending...

  postie [-host:server] -to:address[,...] [-cc:address[,...]] [-bcc:address[,...]]
         -from:address [-repltyto:address] -s:subject [-file:filename|-msg:text|-nomsg] [-html [-alt]]
         [-a:filename ...] [-dir:filespec ...] [-uue] [-high|-low] [-notify] [-url:URL]


For NNTP sending...

  postie -news [-noarchive] [-host:server] -to:newsgroup[,...] [-cc:newsgroup[,...]]
         -from:address [-replyto:address] -s:subject [-file:filename|-msg:text|-nomsg] [-html [-alt]]
         [-a:filename ...] [-dir:filespec ...] [-uue] [-user:userid -pass:password] [-url:URL]


For POP3 retrieving...

  postie [-host:server] -user:userid -pass:password [-br] [-file:filename -raw]
         [-extract:[path]] [-msg:nbr] [-rm] [-relay:hostname [-alias:filename | -to:address]] [-receipt]


For IMAP4 retrieving...

  postie [-host:server] -imap -user:userid -pass:password [-preauth] [-br] [-file:filename -raw]
         [-extract:[path]] [-msg:nbr] [-rm] [-relay:hostname [-alis:filename | -to:address]] [-receipt]
         [-mbox:name] [-create:mbox] [-delete:mbox] [-move:mbox]

For list-server processing...

  postie [-host:server] -rm -user:userid -pass:password -tolist:filename -listserv:address -owner:address [-priv] [-fetch:path [-open]] [-every:mins]


For SMTP queue transfer...

  postie [-host:server] -etrn:domain



OPTIONS:

 -host:hostname - 'hostname' is the name of an SMTP server (or POP3 server),
                  defaults to 'localhost'. Can also be set in a <FORM> with
                  a field name of 'postie_host'.

 -port:service  - optionally specifiy a port number or service name to connect to.
                  Can also be set in the config file 'postie.txt' by the:
                  SMTP, NNTP, POP3 and IMAP4 keywords. You probably will need to
                  specify this ONLY if you are using a non-standard port or go
                  through a relay of some sort.

 -news          - post a newsgroup article (else send mail). Can also be set in a
                  <FORM> with a field name of 'postie_news'. Also, reverses sense
                  of '-map_8bit' option (see below).

 -imap          - read rom an IMAP4 server else POP3 is assumed.

 -noarchive     - when posting to news, set the 'x-no-archive: yes' header so that
                  DejaNews won't store the article.

 -to:address - 'address' is the e-mail address or news-group name of the recipient.
               This option can be used multiple times, or a comma separated list
               may be used.
               NOTE: you can also use addresses of the longer form i.e.
               -to:"Andrew Davison <andrew@infradig.com>" and the older
               variant -to:"andrew@infradig.com(Andrew Davison)". Can also be
               set in a <FORM> with a field name of 'postie_to'.

 -hide       - if set other -to: recipients of the message won't see each other.

 -tolist:filename - 'filename' is a file with one e-mail address per line, used
                    for sending to multiple recipients as an alternative to '-to'.
                    Any line beginning with a '#' is ignored.

 -cc:address - 'address' is the e-mail address of the recipient. This option can
               be used multiple times, or a comma separated list may be used.
               Can also be set in a <FORM> with a field name of 'postie_cc'.

 -cclist:filename - 'filename' is a file with one e-mail address per line, used
                    for sending to multiple recipients as an alternative to '-cc'.
                    Any line beginning with a '#' is ignored.

 -bcc:address - 'address' is the e-mail address of the recipient. This option can
               be used multiple times, or a comma separated list may be used.
               NOTE: other recipients will be hidden from each other. Can also be
               set in a <FORM> with a field name of 'postie_bcc'.

 -bcclist:filename - 'filename' is a file with one e-mail address per line, used
                    for sending to multiple recipients as an alternative to '-bcc'.
                    Any line beginning with a '#' is ignored.

 -high          - set importance as high (default is normal).

 -low           - set importance as low (default is normal).

 -notify         - request read notification (if recipient supports it).

 -receipt       - send a receipt to someone who has requested one.

 -ns            - For non-stop sending mode. Don't stop on send errors, try and
                  deliver to as many recipients as possible. On by default for
                  list-server processing, otherwise off.

 -from:address - 'address' is the e-mail address of the sender.

 -replyto:address - 'address' is the e-mail address to reply to.

 -verify        - verify e-mail 'from' address (as far as possible).

 -s:subject     - is a string used for the subject line, e.g. -s:"This is a test"
                  Can also be set in a <FORM> with a field name of 'postie_subject'.

 -file:filename - SMTP: an optional specficiation of an input text-file for the
                  body of the mail message. If not supplied then standard
                  input is assumed (terminate with CTRL-D).
                  See also '-msg' and '-nomsg' options below.

 -file:filename - POP3/IMAP4: an optional specification of an output file for the body
                  of a mail message. If not supplied then standard
                  output is assumed. If multiple messages are selected
                  for reading then all output will be concatenated to
                  the output file (attachments are extracted inline
                  so this will only work with text messages).

 -sep:string   - output a string between raw message output when using -file:filename option.

 -raw         	- use to copy headers as well as body. Turns off -extract option.

 -nomsg         - SMTP: no message body is sent, just attachments (see above and -a).

 -msg:text      - SMTP: use as message body instead of '-file' or standard-input.

 -msg:nbr       - POP3/IMAP4: select specified message (default is ALL messages).

 -rm            - SMTP: remove file(s) specified by '-file', '-a' & '-url' after use.

 -rm            - POP3/IMAP4: delete the selected message(s). If -br option is
                  used then the messages won't be displayed as they are
                  deleted.

 -html          - optionally specifies use of HTML content type (be
                  sure recipient's mail reader can handle HTML mail
                  before using). Also make sure a <base> document is
                  set in the HTML for embedded images and links. In
                  POP3/IMAP4 mode it formats output to suit display in an
                  HTML browser (and reverses the sense of any
                  'multipart/alternative' content type received). Can
                  also be set in a <FORM> with a field name of 'postie_html'.

 -alt           - HTML input is also translated to plain-text and both are
                  sent as MIME multipart/alternative.

 -a:filename    - where 'filename' is the name of a file to be sent with the
                  mail message as a multipart MIME attachment. The file is removed
                  ONLY if the '-rm' option is also used.
                  This option can be repeated any number of times.

 -url:URL       - where 'URL' is the name of a URL to download and save as a
                  file to (possibly - see -noop option) be sent as an attachment.
				  The file is saved to the current-working directory unless the
                  '-extract:path' option is specified. The file is removed ONLY
                  if the '-rm' option is also used.
                  This option can be repeated any number of times.

 -dir:filespec  - all matching files are included as attachments e.g.
                  '-dir:*' or '-dir:*.log'.
                  NOTE: does not recursively search sub-directories. Can
				  be be repeated multiple times and used in conjunction
                  with '-a:'. Wild-card selection not available under Unix.

 -cnt:number    - send message 'number' times (may be useful for testing?).

 -binary        - force all sent attachments to be binary MIME-type (i.e
                  'application/octet-stream'). This is useful if attaching
                  text and/or HTML files so they don't appear in-line in
                  advanced readers.

 -use_mime:0|1  - send as a MIME message if set to '1' (on by default).

 -map_8bit:0|1  - encode characters as 'quoted printable' content-type
                  if set to '1' (on by default). Otherwise 8-bit characters
                  will go thru unchanged with 7-bit encoding (see -8 option). If
                  '-news' is specified then this option is set to '0' (off by default)

 -8             - use 8-bit encoding (allow 'raw' binary data thru unmodified).
                  This option is off by default and is not recomended to use.

 -user:userid   - IMAP4/POP3/NNTP account userid. Can also be set in a <FORM> with
                  a field name of 'postie_user'.

 -pass:passwd   - IMAP4/POP3/NNTP account password. Can also be set in a <FORM> with
                  a field name of 'postie_pass'.            

 -preauth       - used with IMAP4 servers that are 'pre-authorised'. Basically it
                  reads userid/password but doesn't use them (ie. enter dummy values).

 -auth          - in CGI mode use HTTP Basic Authentication scheme instead of
                  user/pass params (this is *slighly* more secure).

 -redirect:url  - output is an HTTP "Location:" header to redirect browsers.
                  Used with '-cgi' option only.

 -mime:mimetype - sets the output mime-type (default is 'text/html'). Used
                  with '-cgi' option only, and necessary if used with an
                  HTML <IMG> tag in conjunction with the '-redirect' option.
                  You can run multiple POSTIE commands by using <IMG> tags
                  with harmlessly redirected reponses, or use be daring
                  and use the <OBJECT> tag to embed text responses.

 -cgi:query-string - the command-line is actually an HTTP query-string and text
                     input is taken from a file in either 'c:\temp' or
                     '/usr/tmp' depending upon platform. This is for
                     security reasons so that any arbitrary file cannot
                     be grabbed. You can change the path using the POSTIE_PATH
                     environment variable e.g. 'set POSTIE_PATH=c:\uploads'. Any
                     files specified by '-file:' or '-a:' are taken to be relative to
                     this path (and '..' is checked for!). See also the
                     '-post' option.

 -post          - data input is via CGI POST method rather than a file. Used
                  with '-cgi' option only. 

 -import        - read an input control stream (see import.txt)

 -t             - read a Unix sendmail compatible input stream to send mail or news (see -news).
                  Recognises standard headers.

 -every:mins    - check POP3/IMAP4 server every 'n' minutes.

 -v[:level]     - verbose output at designated level (default level is 1 if just '-v').

 -q             - disables message-sent confirmation and a few others.

 -log:filename  - appends status info to log file.

 -br            - list basic POP3/IMAP4 headers only (else message text gets displayed).

 -relay:hostname    - relay mail messages to specified host. Can use the '-to:address'
                      option with this to force sending to a specific user, otherwise
                      the relay host will have to resolve mailbox addresses. This can
                      be useful whrn you can't create a .forward file on the original
                      server but want you mail sent on to you somewhere else. Turns
                      off -br option automatically.

 -extract[:path]     - extract attachments to separate named files, in current-directory or named path.

 -get:name    - used to retrieve an attachment in CGI mode.

 -config      - read the 'postie.txt' configuration file (see sample file in this directory).

 -listserv:address - set the from/return address on list posts.

 -priv            - when used with -listserv means that the list is private and only the list owner
                    can post to the list (i.e. a mailing list), otherwise the list is considered public
                    (i.e. a discussion list).

 -owner:address   - declares ownership and address for control messages.

 -fetch:path   - specifies a path to which file 'fetch' requests are relative to. Oterwise fetch
                 is diabled. Only list subscribers may issue fetch requests.

 -open         - if specified then anyone can fetch files (see above), not just subscribers.

 -noatt        - if specified then binary-attachments are dropped.

 -uue          - attachments OR message are UUencoded before being sent.

 -probe:address   - test that 'address' is a acceptable to designated host WITHOUT sending any mail. Use
                    DNS Mail Exchanger info to do the lookup on the actual mail host. use the -host option
                    as well to specifiy a name server (if not 'localhost').

 -mx              - Send mail directly to a recipients mail server rather than routing locally. Use with -host:name
                    to specify a DNS server to use for Mail eXchanger lookup.

 -charset:string  - set the character-set to be used in the MIME headers. The default is 'iso-8859-1'
                    for Western European. Can be set in config file as 'CHARSET string' as well.

 -mbox:name      - (IMAP4) set the current mailbox (i.e. folder) for reading (default is INBOX).

 -create:mbox    - (IMAP4) create named mailbox.

 -delete:mbox    - (IMAP4) delete named mailbox (if no subordinates).

 -move:mbox      - (IMAP4) move selected message(s) to named mailbox.

 -list:string    - (IMAP4) list selective mailboxes. For example '-list:"personal/*"' will list all the folders
                   under 'personal' (including sub-sub-folders). Use '-list:"personal/%"' to list just the
                   first sub-level. Use '-list:"%"' to list just the top-level. Of course the delimiter '/' may
                   be different on your system (is probably '\' on Windows systems).

 -list           - (IMAP4) list all mailboxes (same as '-list:"*"' option).

 -alias:filename - When relaying use file to translate addresses. Each line of the file is of the form
                   'alias: address' and lines beginning with '#' are ignored. Any address encountered
                   that matches 'alias' will be translated to 'address'. Can be useful with masquerading.
                   Address formats will converted where appropriate and comparison is not case-sensistive.

 -exec:command    - on POP3/IMAP4 read, execute 'command' passing message body to standard-input.

 -limit:n         - send mail to lists in batches of 'n'. gets around TCPT-TO limits on mail servers.

 -xit             - (POP3/IMAP4) Sets exit code to the number of messages queued for reading (on Windows you
                    may need to divide by 256).

 -etrn:domain     - initiate remote SMTP transfer of queued mail (See RFC 1985).

 -org:name        - the organization name (e.g. -org:"Microsoft Corp.").

 -sens:desc       - describe the 'sensitivity' of the message (e.g. -sens:"Top Secret (for your eyes only)")


EXAMPLES:

Sending mail...

    postie -host:mailserver.com -from:fred@here -to:joe@there -s:"Here it is..." -nomsg -a:file.zip
    postie -from:fred@here -to:joe@there -to:fred@there -s:"Hello there" <file.txt
    postie -from:fred@here -to:joe@there -s:"Hello there" -msg:"This a mail message"
    postie -from:fred@here -to:joe@there -s:"Hello there" -html -file:file1.html
    postie -from:fred@here -to:"Joe Blow <joe@blow>" -s:"Hello there" -msg:"This a mail message"


Posting contents of an HTML form...

    <form method=POST action="/cgi-bin/postie.exe?-cgi:-from:fred@here&-to:joe@there&-s:Enquiries+form&-post&-redirect:/enquires/done.html">


Send e-mail from an HTML form...

	<form method=POST action="/cgi-bin/postie.exe?-cgi:-post&-from:me@here.com">
	<input type=hidden name=postie_host value="here.com">
	Subject: <input type=text name=postie_subject size=72><br>
	To: <input type=text name=postie_to size=72><br>
	Cc: <input type=text name=postie_cc size=72><br>
	Bcc: <input type=text name=postie_bcc size=72><br>
	<textarea name=postie_data cols=72 rows=10 wrap></textarea><br>
	<input type=checkbox name=postie_html> HTML mail?
	<input type=checkbox name=postie_news> To newsgroup?
	<input type=submit name=postie_submit value="Send">
	</form>

	The 'host' and 'from' values can also be set in a config file called 'postie.txt' which should be in the same
    directory as the POSTIE executable or in the home directory of the account the CGI runs as (depending of course
    upon which Web server is in use). See sample file 'postie.txt' in this directory.


Sending news...

    postie -news -host:newsserver.com -from:fred@here -to:alt.test -s:"Test: ignore" -msg:"Testing" [-user:userid -pass:secret]


Deliver URL by e-mail...

    postie -host:mailserver.com -to:fred -s:"Here it is" -nomsg -url:http://somewhere.com/help/readme.txt -rm


Get URL...

    postie -noop -extract:c:\temp -url:http://somewhere.com/help/readme.txt


Listing mail...

    postie -host:mailserver.com -user:userid -pass:secret -br
    postie -host:mailserver.com -user:userid -pass:secret -br -imap -mbox:personal


Retrieving mail...

    postie -host:mailserver.com -user:userid -pass:secret -msg:1 -file:mail.dat -extract -rm


Relaying mail from a drop box...

    postie -host:mailserver.com -user:userid -pass:secret -relay:localserver.com -rm


Relaying masqueraded mail...

    postie -host:mailserver.com -user:userid -pass:secret -relay:localserver.com -alias:alias.txt -rm

	Create a file 'alias.txt' like...

          "John Smith" <account@mailserver.com>: john@localserver.com
          "Mary Jones" <account@mailserver.com>: mary@localserver.com
          account@mailserver.com: postmaster@localserver.com

    and note: the last entry is a 'catch-all' to pick up any other mail items. You can leave this out if you
    need to mix masqueraded and 'real' mail in the one account as unmatched items will not be deleted when -rm
    option used.


Forwarding mail to a user...

    postie -host:mail.ozemail.com.au -user:adavison -pass:secret -relay:mail.dvp.com.au -to:andrewd -rm


Web mail...

	See getmail.asp and/or getmail.pl for details.

	The demonstration site has been removed due to persistent hacking attempts and a subsequent tightening of
    security at my employers site.

    The demonstration site has been provisonally re-instated...

       http://home.dvp.com.au/webmail

          userid: dummy
          passwd: dummy

          (no offence intended)

    Be good or be gone.


List-server...

	postie -host:mail.dvp.com.au -user:postie-list -pass:secret -listserv:postie-list@dvp.com.au -tolist:postie.lst -owner:adavison@ozemail.com.au -log:postie-list.log -rm

   Send messages with 'subscribe' or 'unsubscribe' as the subject to control the list. Posts sent to the
   list will be distributed to all members of the list and will be seen as originating from the list (that
   is their e-mail address will not be displayed unless a signature is included). This means that replying
   to a posting will go back to the list. This may annoy some people, but it's how i've always wanted lists
   to work and saves a lot of bother if you ask me. Undeliverable message returns will not flood the whole
   list as only subscribers are allowed to post.

   Note: this may be moot, but it is certainly possible for a client with just one mailbox to use masquerading
   (see below) to run multiple lists.

   Can now request files with 'index' (or 'dir') or 'fetch filename' (or 'get filename') as the subject. Selected files are
   returned as an e-mail attachment. Requested files are relative to the '-fetch:path' directory if specified. If not
   specified then fetch mode is disabled. Only list subscribers may fetch files unless '-open' is used.

   The following CRONTAB entry periodically (every 15mins) checks for mail to process...

       0,15,30,45 * * * * /home/postie-list/postie -user:postie-list -pass:secret -rm -priv
                                -listserv:postie-list@dvp.com.au -tolist:/home/postie-list/postie.lst
								-fetch:/home/postie-list/fetch -open -owner:adavison@ozemail.com.au
                                1>> /home/postie-list/postie.log 2>> /home/postie-list/postie.err

   

Auto-dialling...

	The following example is for NT...

		postie -connect:"My ISP" -noop
		...
		postie -disconnect:"\"My ISP\" /disconnect" -noop

				or

		postie -connect:"My ISP" options... -disconnect:"\"My ISP\" /disconnect"

	And note the use of escaped embedded back-slashes on the -disconnect.

	The configuration file 'postie.txt' MUST contain a line specifiying the dialler
	program to use...

		DIALER rasdial           - for NT
		DIALER rasdial95         - for 95 (a shareware product I believe) 

	Sorry about the mispelling. Something suitable will be available for other platforms.


Masquerading...

	Added mailbox masquerading using '-masq:username' option. This can
	be useful where you have only one mailbox account but multiple
	users. Each user sends mail with a from address of the form...

	  -from:"John.Smith <account@mailserver.com>"       OR
	  -from:"Mary.Jones <account@mailserver.com>"

	Then each individual's mail can be retrieved as follows...

	  postie -host:mailserver.com -user:account -pass:secret -masq:"John Smith"
  	  postie -host:mailserver.com -user:account -pass:secret -masq:"Mary Jones"

	Masquerading allows you to share a mailbox! The naming comes from Linux
	IP Masquerading which does the same thing but for IP addresses. You would
	probably want to use this feature with the '-relay' option to dump to local
	accounts, or in CGI mode using Web mail.

    You will probably now want to use the new -alias:filename option instead of
    multiple commands using -masq.


Language:

To customise the output for non-English language (especially in Web Mail) copy the
following to the 'postie.txt' configuration file...

STRING_Folder <== Folder 
STRING_Moveto Move to ==> 
STRING_Delete Delete 
STRING_Forward Forward... 
STRING_Reply Reply... 
STRING_Newsgroup Newsgroup? 
STRING_Trace Trace? 
STRING_Send Send 
STRING_View View... 
STRING_Create Create ==> 
STRING_Compose Compose...
STRING_Logout Logout
STRING_Bcc Bcc 
STRING_Cc Cc 
STRING_To To
STRING_From From
STRING_replyto Reply-To
STRING_Date Date
STRING_Subject Subject 
STRING_Wrote Wrote: 
STRING_Thereare There are 
STRING_Messageswaiting messages waiting 
STRING_Deletemessage Delete message # 
STRING_Inlineattachment Inline attachment?
STRING_Importance Importance
STRING_Sensitivity Sensitivity
STRING_Organization Organization
STRING_ReceiptTo Disposition-Notification-To

Modify each line after the first space character to suit.



COMPILING:

You will NEED a C++ compiler, not C.

    cd postie/src
    nmake -f makefile.nt        // MSVC++ v4 32-bit (or use compile.bat)
    nmake -f makefile.nt        // MSVC++ v5 32-bit (or use compile2.bat)
    nmake -f makefile.win       // MSVC++ v1 16-bit (or use compile16.bat)
    make -f makefile.b32        // Borland C++ 32-bit (or use (compileb.bat)
    make -f makefile.unx        // Unix (you will probably need GNU C++)
	cd ../client
	- as above -


MAILING LIST:

Send a message with a subject of 'subscribe' or 'unsubscribe' to 'postie-list@dvp.com.au'
to receive news about updates etc...

   mailto:postie-list@dvp.com.au?subscribe


MISCELANEOUS:

Bug reports, compatability problems, recommendations for improvements etc gratefully received.


POLICY

My software publishing policy is... release often! This may mean that bugs are more
frequently let loose than you or I may like, but it also means that new features have
the chance to be shopped around before they are set hard and fast.



