emailler/README-emailler.md

Apple II Email Suite

The following programs are completely new:

• POP65 is a Post Office Protocol version 3 (POP3) client for the Apple II with Uthernet-II card.
• EMAIL is a simple user interface for reading and managing email. It works together with POP65.
• SMTP65 is a Simple Mail Transport Protocol (SMTP) client for the Apple II with Uthernet-II card.

Overview

System Setup and Configuration

Configuration File

The system configuration file is called POP65.CFG. It is a straightforward ProDOS text file, with one parameter per line. You may edit this file using any ProDOS text editor. When editing the file be careful not to add or delete any lines - this file has no grammar and the lines must appear in the expected order.

All three of the mail programs POP65.SYSTEM, EMAIL.SYSTEM and SMTP65.SYSTEM share this configuration file.

Here is an example config file (with passwords replaced with **** for obvious reasons):

192.168.10.2
pi
******
NODELETE
192.168.10.2
apple2.local
/H1/DOCUMENTS/EMAIL
bobbi.8bit@gmail.com

The lines are as follows, in order:

1. IP address of the POP3 server for receiving new mail.
2. Username to use when connecting to POP3.
3. Password for POP3 connection (in plaintext).
4. If this string is exactly DELETE then messages will be deleted from the POP3 server after downloading. Otherwise they are left on the server. DELETE is the normal setting, but NODELETE (or any other nonsense value) can be helpful for debugging, allowing the same messages to be downloaded from the POP3 server again and again.
5. IP address of the SMTP server for sending outgoing mail.
6. Domain name that is passed to the SMTP server on connection. The way my SMTP server (Postfix) is configured, it doesn't seem to care about this.
7. ProDOS path to the root of the email folder tree. Mailboxed will be created and managed under this root path.
8. Your email address. Used as the sender's address in outgoing messages.

Creating Directories

To get started, you will need to create the following directories:

• The email root directory (/H1/DOCUMENTS/EMAIL in the example config)
• The SPOOL directory, used by POP65, within the email root directory. This will be /H1/DOCUMENTS/EMAIL/SPOOL for our example configuration.

You can create these directories in ProDOS BASIC.SYSTEM as follows:

] CREATE /H1/DOCUMENTS/EMAIL
] CREATE /H1/DOCUMENTS/EMAIL/SPOOL
] CREATE /H1/DOCUMENTS/EMAIL/INBOX

Mailboxes

Each mailbox consists of the following:

• A directory under the email root, and within this directory
• Optionally, email messages in plain text files named EMAIL.nn where nn is an integer value
• A text file called NEXT.EMAIL. This file initially contains the number 1. It is used when naming the individual EMAIL.nn files, and is incremented by one each time. If messages are added to a mailbox and nothing is ever deleted they will be sequentially numbered EMAIL.1, EMAIL.2, etc.
• A binary file called EMAIL.DB. This file contains essential information about each email message in a quickly accessed format. This allows the user interface to show the email summary without having to open and read each individual email file. This file is initially empty and a fixed size record is added for each email message.

The easiest way to create additional mailboxes is using the N)ew command in EMAIL.SYSTEM.

POP65.SYSTEM knows how to initialize INBOX but the directory must have been created first.

POP65.SYSTEM

POP65 is a Post Office Protocol v3 (POP3) client for the Apple II. It requires an Uthernet-II ethernet card and will not work with other interfaces without modification, because it uses the W5100 hardware TCP/IP stack. POP65 is used to download new email messages from a POP3 email server. (I use Dovecot on the Raspberry Pi as my POP3 server, but other POP3 servers should work too.)

POP65 runs without any user interaction and performs the following tasks:

• Detect Uthernet-II
• Obtain IP address using DHCP
• Connect to POP3 server using parameters from first three lines of POP65.CFG
• Enquire how many email messages are waiting (STAT command)
• Download each email in turn (RETR command) and store it in the SPOOL directory.
• If configured to delete messages on the POP3 server, messages are deleted after successful download (DELE command)
• Once all messages have been downloaded, disconnect from the POP3 server (QUIT command)
• Scan each downloaded message in the SPOOL directory and import the message into INBOX:
  • Read INBOX/NEXT.EMAIL to find out the next number in sequence and allocate that for the new message.
  • Copy the message from SPOOL to INBOX/EMAIL.nn (where nn is the next sequence number) while scanning it for the following information:
    • Sender (From:) header
    • Recipient (To:) header
    • Date and time (Date:) header
    • Subject (Subject:) header
    • Offset in bytes to start of message body
  • Store all of the information obtained from scanning the message in INBOX/EMAIL.DB.
  • Update INBOX/EMAIL.nn, incrementing the number by one.
  • Iterate until all messages in SPOOL are ingested into INBOX.

EMAIL.SYSTEM

SMTP65.SYSTEM

SMTP65 is a Simple Mail Transport Protocol (SMTP65) client for the Apple II. It requires an Uthernet-II ethernet card and will not work with other interfaces without modification, because it uses the W5100 hardware TCP/IP stack. POP65 is used to send outgoing email messages to an SMTP email server. (I use Postfix on the Raspberry Pi as my SMTP server, but other SMTP servers should work too.)

...