(An HTML version of this document is available at http://www.isaac.cs.berkeley.edu/pilot/TGpostman/ ) From the producers of Top Gun Telnet and Top Gun ssh... _________________________________________________________________ [INLINE] [INLINE] [INLINE] [INLINE] Top Gun Postman Version 1.2 beta [ Introduction | What's New | Installation | Configuration | Composing Mail | Sending Mail | Receiving Mail | FAQ | Terms, Conditions, and Disclaimer ] _________________________________________________________________ Introduction Top Gun Postman is a POP3/APOP3 and SMTP capable mail dispatcher that runs on the Palm Pilot Professional. Top Gun Postman enables you to send mail messages that you have composed offline, and retrieve mail messages that are waiting for you in your POP3/APOP3 accessible mail spool. Top Gun Postman is not a complete mail package - it relies on the built-in Mail program that is distributed with the Palm Pilot Pro for the composition and viewing of messages. This release is a beta version of the program, which means that although we believe we've eliminated most of the bugs, you may still run across a few. If so, please report them. Feedback is encouraged; you can reach the developers at . What's New Version 1.2 beta incorporates the following new features and bug-fixes: * The progress bar no longer jumps to the top of the screen if the Pilot is tapped during a download. * The Pilot no longer times out and turns itself off during long downloads. * Sometimes the "Send Mail" button used to act like the "Both" button - this is fixed. * Many people reported weird crashes; we traced this to the Pilot function FrmCustomAlert(), which is supposed to bring up an error dialog box. Unfortunately, it seems to be buggy and will often crash the Pilot instead. We removed the call to this routine and replaced it with our own error dialog box. * Top Gun Postman now correctly redials your modem if it had tried before and failed. The recommended way to disconnect PPP is still to push the green button. * Added an option to paste extra headers at the bottom of each message. The old options to paste them at the top, or not at all, are still present. * Added To: and Cc: headers to the query dialog, so you can see (for example) to which mailing list the message was sent. * Added the standard Edit menu to the Preferences screens. * Added an option to select message truncation size. The "Mem" choice means to download as much as will fit in a memory record; other choices limit the message to between .5 KB and 16 KB. * Added an option to delete messages from the server only if they were completely downloaded (not truncated). Version 1.1 beta incorporated the following new features and bug-fixes: * Top Gun Postman now handles the downloading of large messages more gracefully. If a message is too large, the entire messaage will be downloaded, but only as much of the message as can be put in an Inbox record is saved. This is usually between 20-24KB worth of data, but sometimes as large as 32KB. You will notice a "message truncated" status indicator in the download progress screen if this occurs. * A new button has been added to the main screen that sends SMTP mail and receives POP mail in one fell swoop. * Top Gun Postman notices and obeys "Status:" headers. If you select "Save only unread messages" in the POP preferences screen, and if a downloaded message contains a Status header with the "R" flag set (i.e. the message has been read before), the message will not be saved in your Inbox. * A potential memory leak was plugged. This memory leak would only be tickled if the server does not understand TOP, you have selected "Paste extra headers", and you have selected "Query for each message". (Bet you're wondering how we figured that one out, eh?) * Your POP password is no longer displayed in the POP preferences form. * "X-Mailer:" and "X-URL:" headers are added to outgoing messages. * Graffiti state indicators were added to the preferences forms. Downloading and Installing Top Gun Postman 1. Download TGpostman-1.2.zip and unzip the archive. 2. Install TGpostman.prc on your Pilot (using Pilot Desktop on your Windows machine or pilot-xfer on your Unix machine). You are now ready to configure Top Gun Postman. Configuring Top Gun Postman 1. Ensure that your Network and Modem preferences on your Pilot are set correctly to establish a PPP connection. 2. Open the TG Postman application. You should see a screen that looks like this: [INLINE] 3. Tap on the Menu button to bring up the menus. 4. Tap on the About menu, and select About.... Enjoy our cool attribution and the 1 bit photo of ourselves. 5. Tap on the Menu button, and select the SMTP Prefs... item under the Options menu. You should see a screen that looks like this: [INLINE] 6. Enter the hostname or IP address of your SMTP server in the first field. 7. Enter your email address in the second field. 8. Enter your real name in the third field. 9. Tap on the Save button. 10. Select the Pop Prefs... item under the Options menu. You should see a screen that looks like this: [INLINE] 11. Enter the hostname or IP address of your POP3 server in the first field. 12. Enter your POP3 username in the second field. 13. Tap on the Tap to enter box to bring up the password box, which looks like this: [INLINE] 14. Enter your POP3 password in the field, and tap on OK. 15. If you are using APOP, tap on the checkbox next to Use APOP. 16. If you want to see headers other than To:, From:, Cc:, and Subject:, pop up the list next to Paste extra headers, and select either "Top" or "Bottom". These extra headers will appear at the beginning of the message if you select "Top", or at the end of the message if you select "Bottom". Selecting "No" will suppress the extra headers. 17. If you want incoming messages to be truncated automatically at a certain size, select that size from the popup list next to Truncate messages at. If you want as much of incoming messages as possible to be stored, select the "Mem" option from the list; this will cause Top Gun Postman to truncate the message only when it cannot allocate any more memory for it. This memory limit is usually around 20-24K, but sometimes is as large as 32K or more. 18. If you want to automatically delete messages from the server after downloading them, select "Yes" from the popup list next to Delete from server. If you select "No", messages will stay on the server after you download them. If you select "If complete", messages will be deleted from the server only if they were not truncated during download. 19. If you want Top Gun Postman to not save any messages that you have read before, tap on the checkbox next to Save only unread messages. This is useful in case you have lots of previously viewed messages in your POP3 mailspool that you don't want cluttering up your inbox. Top Gun Postman detects previously read messages by noting that the R status flag is set in a Status: header. 20. If you want Top Gun Postman to query you for what to do before downloading each message (giving you the opportunity to view the headers for a message before downloading it), tap on the checkbox next to Query for each message. This is useful in case people like sending you postscript or large MIME inclusions by email. If this option is selected as well as Save only unread messages, you will NOT be queried regarding previously read messages. 21. Tap on the Save button. You are now ready to use Top Gun Postman. Using Top Gun Postman Composing Mail To compose mail, use the Mail application that is built into the Palm Pilot Professional. Your composed mail will be filed in your Outbox, which is where Top Gun Postman will look for messages to send. If the very first line of your mail message is ## (on a line by itself), then all subsequent lines until a completely blank line are treated as additional headers. Sending Mail To send previously composed mail, launch TG Postman and tap on the Send mail button. Top Gun Postman will attempt to start a PPP session (if one hasn't already been started), and then will connect to the configured SMTP server and send your mail. All successfully sent mail messages will be refiled in the Filed folder. Receiving Mail In order to receive new mail messages, launch TG Postman and tap on the Get mail button. Top Gun Postman will start a PPP session (if necessary), and then will connect to the POP server. Once authentication has succeeded, Top Gun Postman will begin downloading messages. You should notice a dialog box that looks like the following while messages are being downloaded: [INLINE] The "Retrieving message X of Y" indicator tells you how many messages are in your POP mail spool, and the status bar below this indicates the download progress of the current message. If you have indicated that you want Top Gun Postman to query you for each message, a dialog box will pop up after the header of each message is downloaded; this dialog box contains two buttons and a checkbox as well as the message headers and size, and should look like this: [INLINE] If your POP3 server does not support the "TOP" command, you won't be able to preview the message headers, and will only see the message size. Select an entry from the Delete from server popup list if you want to change the default delete behavior for this message; the entries have the same meanings as in the POP Preferences screen. Then, tap on either the Get Message or the Skip Message button depending on whether you want the message to be retrieved or not. Note: if you tap on Skip Message, but have Delete from server set to "Yes", the message will not be downloaded but will be deleted from the server. All downloaded messages will be automatically filed in your Inbox. If you hit the Cancel button in the middle of a POP3 mail transfer, any already downloaded messages will be preserved on your Pilot, but no messages will be deleted from the POP3 server. Note: to send your outgoing messages and download your POP mail all at once, you can tap the Both button at the bottom of the main title screen. Frequently Asked Questions 1. Why can't Top Gun Postman drop my PPP connection when I'm done downloading/sending mail? Top Gun Postman doesn't control PPP - Palm OS automatically forges the default PPP connection when the network library is accessed. A useful trick, however, is to simply turn off the Pilot by pressing the green button instead of going to the Network preferences screen to manually disconnect PPP. Turning off the Pilot causes an open PPP connection to be gracefully shut down. 2. What is the maximum message size that Top Gun Postman handles? Mail Inbox records are limited to roughly 32KB in size by Palm OS, so we cannot store mail messages larger than this. We do gracefully handle large messages by truncating them as needed. 3. Can Top Gun Postman handle file attachments? Nope. Maybe in the future, but no promises. Credits, Terms, Restrictions, and Disclaimers Top Gun Postman (aka TG Postman) was written by Ian Goldberg and Steve Gribble. If you feel so inclined, you may send money, postcards, t-shirts, or anything else you think we'd like to: Ian Goldberg and Steve Gribble Soda Hall #1776, UC Berkeley Campus Berkeley, CA 94720-1776 USA Comments, bug reports, success and failure stories are welcome; send them to the pilot-unix list or to the developers at . Back to the ISAAC Group's Pilot page _________________________________________________________________ This software is copyrighted by the Regents of the University of California. The following terms apply to all files associated with the software unless explicitly disclaimed in individual files. The authors hereby grant permission to use, copy, modify, distribute, and license this software and its documentation for any purpose, provided that existing copyright notices are retained in all copies and that this notice is included verbatim in any distributions. No written agreement, license, or royalty fee is required for any of the authorized uses. Modifications to this software may be copyrighted by their authors and need not follow the licensing terms described here, provided that the new terms are clearly indicated on the first page of each file where they apply. IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. _________________________________________________________________ Ian Goldberg / iang@cs.berkeley.edu Steve Gribble / gribble@cs.berkeley.edu Last modified: Mon Jul 7 14:09:15 1997