Developers Guide

i-Mail allows developers and the like to send messages from within custom applications. To do so you will need a fundamental understanding of how e-mail messages are formatted and how to interface with i-Mail. This document only discusses how to integrate file based systems with i-Mail. To use TCP/IP to interface with i-Mail you should use the standards defined for the SMTP and POP protocols.

The i-Mail directory structure:

What the directories are used for

SPOOL Directory:	Mail that is collected from a POP server is stored in this directory and is processed on the 'local' processing schedule. i-Mail determines whether mail should be moved to users directories, to the outbox directory or both. i-Mail also uses this directory when it needs to send mail to a local user or to the postmaster.
OUTBOX Directory:	Mail that is destined for remote hosts, either at an unknown domain or a defined remote domain are placed in this directory along with one or more recipient list files indicating where the messages are to be sent.
USERS Directory	Mail for users on hosted domains are stored here in individual mail directories.
Custom Directories	These are directories defined in the 'Mail Scan' tab in i-Mail admin. Custom directories are used to interface i-Mail with third party applications.

Directory Usage Notes

You should never place data directly into the SPOOL, OUTBOX or USERS directories unless directed to do so by a support engineer at Digital Integration. i-Mail expects files in these directories to be closed when it reads them. Flagrant disregard for the file handling functions of i-Mail could cause your server to abend.

How to interface your programs with i-Mail

The process of giving i-Mail message files to send is a relatively simple task. Basically you create a message in a custom directory and i-Mail will send it. These are the things you need to do to ensure a happy and productive relationship with i-Mail. Keep in mind that i-Mail has direct access to the information on the server hard disk and, because of this, has much faster access to the files. If you simply copy a file into a custom directory i-Mail may detect and start sending the file before you have finished writing it. Although the chances of this happening are very low, as i-Mail scans the custom directories every two seconds, it is better not to let this circumstance arise.

i-Mail specifically looks for messages with an extension of MSG. The name of the file is irrelevant and you may wish to use your own naming standard and duplication prevention code when you write the files. If you are creating a product that is going to be used by other organisations it is recommended that you use a file naming convention that is unique to your product. It is unlikely that you will have a problem as you can specify that i-Mail uses your directory for your messages only.

There are two methods of safely creating message files in the i-Mail Mail Scan directories.

Method 1: Create a file with an LCK extension and then create the MSG file of the same name. When you have finished writing the message file, delete the LCK file. i-Mail will not process message files that have an associated LCK file and you can take as much time as you like creating the message.

Method 2: Create a message file with an extension other than MSG. When you have finished writing the file, rename it to a file name with MSG as the extension.

Message Formatting and Delivery Addresses

When writing message files you must adhere to a number of rules for successful delivery of mail. If you do not create messages in the correct format, i-Mail will simply move the messages into the 'BadMsgs' folder.

Message file components

Header
Empty Line
Body

Header

All fields in the header of a message are formatted in the following format: field_name: field_value<cr><lf>

More specifically: Field name, prefixed with a colon (:) and a space, followed by what the field contains and terminated by a carriage return and line feed (ascii 13, ascii 10)

For example: To: <jbloggs@company.com>

Required fields are:

To: <e-mail address>

Some useful optional fields are:

From: <e-mail address>
Subject: Subject
Reply-To: <e-mail address>
Organization: Organization name

The last header line must be followed by a blank line, which is made up of a <cr><lf> pair (ascii 13, ascii 10).

Body

The body of the message should be formatted so that each line contains no more than 80 characters per line. Each line should be terminated by a <cr><lf> pair. If you create long lines, the recipients e-mail reader may not be able to display the messages correctly. For more information on writing e-mail messages, refer to the RFC822 message standard.

Addressing the message

The addressing in the header of a message is required for i-Mail to determine recipients. i-Mail will scan the message header for 'To:' lines and create recipient lists from these lines. If you have many e-mail addresses for a message you can create multiple 'To:' lines. You do not need to make any additional files, simply ensure that the message has a valid 'To:' line.

It is good practice to include the 'From:' field so that e-mail may be returned if the message is either replied to or is unable to reach the intended recipient.

Sample Code

These two fragments of code should give a idea of how to start creating your own mail-enabled system.

BASIC

DIM UserList(5) AS STRING
DIM LineTerminator AS STRING
DIM i AS INTEGER
UserList(1)="John.Smith@company.com"
UserList(2)="Robert.Ford@company.com"
UserList(3)="Jenny.Silver@company.com"
LineTerminator=chr$(13)+chr$(10)

OPEN "F:\MAILDIR\MESSAGE.LCK" FOR OUTPUT AS 1
PRINT#1,"LOCKED"
CLOSE 1

OPEN "F:\MAILDIR\MESSAGE.MSG" FOR OUTPUT AS 1
FOR i=1 TO 3
PRINT#1,"To: "+UserList(i)+LineTerminator;
NEXT i
PRINT#1,"From: Manager@company.com"+LineTerminator;
PRINT#1,"Subject: New Mail List"+LineTerminator;
PRINT#1,LineTerminator;
PRINT#1,"This message is notification that you are on"+LineTerminator;
PRINT#1,"the new notification list"+LineTerminator;
CLOSE 1

KILL "F:\MAILDIR\MESSAGE.LCK"

C++

#include <stdio.h>
#include <string.h>

#define MAX_ADDRESS_LENGTH 256

void main()
{
FILE *MessageFile;
char UserData[MAX_ADDRESS_LENGTH*3];
char *UserList[3];
int idx_Address;

strcpy(UserList[0],"John.Smith@company.com");
strcpy(UserList[1],"Robert.Ford@company.com");
strcpy(UserList[2],"Jenny.Silver@company.com");

MessageFile=fopen("F:\\MAILDIR\\MESSAGE.LCK","wb");
fprintf(MessageFile,"LOCKED");
fclose(MessageFile);

MessageFile=fopen("F:\\MAILDIR\\MESSAGE.MSG","wb");
for(idx_Address=0;idx_Address<3;idx_Address++) fprintf(MessageFile,"To: %s\r\n",UserList[idx_Address]);
fprintf(MessageFile,"From: Manager@company.com\r\n");
fprintf(MessageFile,"Subject: New Mail List\r\n");
fprintf(MessageFile,"\r\n");
fprintf(MessageFile,"This message is notification that you are on\r\n");
fprintf(MessageFile,"the new notification list\r\n");
fclose(MessageFile);

remove("F:\\MAILDIR\\MESSAGE.LCK");
}