Setup mapi mail

Theory / The logic behind it all

The big picture

The integration consists of three parts: The SuperOffice program itself, the Somail program and the Somagate program.

What basically happens when you send an email is this:

1. You send an email in the same manner, as you would write a "normal" document, except that you select one of the email templates.
2. SuperOffice produces a .som-file and goes through it and replaces the template tags with SuperOffice data.
3. SuperOffice will start the program Somail.exe with the file name as a parameter.
4. Somail.exe will read the .som-file and show it in the users default email client.
5. When the user chooses send from the client, a copy of the mail will go to the Somagate account.
6. Somagate, which has its own email account, will detect a new email and look for the file used as a parameter when Somail.exe was started. This filename is located in the bottom of the body of the mail.
7. When the filename is located and the actual file is found, Somagate will save the mail with the appropriate name and in the appropriate place.

The next chapters discuss in detail how the different parts work and how the templates and .som-files look like.

The SuperOffice Mail format (.som)

SuperOffice uses Simple MAPI ( for convenience SMAPI ) to communicate with the mail system. Since we couldn't find any suitable standard for saving emails to disk, we created our own. Please welcome the "SuperOffice Mail"-format.

The mail format is text based and looks a lot like a standard .ini-file. This may be because it actually is a .ini-file, but no sudden conclusions should be made. The file has the necessary information used to send an email. It contains the name and email address of the originator and the recipients. It contains the subject, the body and the attachments (special handling here, I'll mention it further down).

A typical .som file will look like this:

[SoMail]
Flags=1
Subject=The email format

[From]
Name=Rune Melhus (SuperOffice ASA)
Address=SMTP:runem@superoffice.no

[SoMaGate]
Name=SuperOffice archive
Address=SMTP:Sniffer@superoffice.no
Type=3

[To 1]
Name=Erik Eide (SuperOffice ASA)
Address=SMTP:erik@superoffice.no
Type=1

[Message]
So, this is how the mail format looks like...

Best regards,
Rune

--
Rune Melhus
SuperOffice ASA
Tel. +47 22 51 70 00
Direct phone: +47 22 51 70 28
Our ref: [RM\1998.2\SUPER001]

However, if the email contains an attachment, the .som-file will suddenly turn into a zip-file. This because we want to keep the mail data, text and attachments together. You can see the filename located at the bottom right after "our ref.:".

The flags field have the following values:
1 = Email unread
4 = Email is read and saved

A .som-file "with attachments" will look like this when opened in WinZip:

The attachments will be there with their original names, while the information about the email is located in the file message.ini.

The email templates
The email templates are just ordinary .som-files with template tags instead of actual data. The "Mail.som", which is a part of the SuperOffice 4.5 release, looks like this:

[SoMail]
Padd=
Subject=

[SoMaGate]
Name=
Address=

[From]
Name= ()
Address=

[To 1]
Name= ()
Address=

[Message]

----------------------------------------------------------------

mailto: 
Phone:
Fax:

----------------------------------------------------------------

The tag is replaced by the filename of the .som file. The directive is also the method Somail uses to separate a template .som-file from a "normal" .som-file. The result is that if you double-click on a template, it will be shown in Notepad, while a normal .som-file will be shown in the email client.

All of the e-mail templates are saved by default to the SuperOffice Archive, except for the forward.som template. This means that if you want the Gateway to store the e-mail, you add the [SoMaGate] section and select "Save to document database" when you define the template.

However, if you do not want the e-mail to be saved, please leave the [SoMaGate]-section and select "Do NOT save to document database" when you define the template.

The email integration comes with six templates. These are:

Template name
Template name
 Used for
 
Faxdoc.som
 Sending a document as a fax.
 
Forward.som
 Forwarding e-mail.
 
mail.som
 Sending an e-mail message.
 
Maildoc.som
 Sending a document as an attachment to an e-mail message.
 
Mailinc.som
 Incoming e-mail template.
 
Reply.som
 Replying to e-mail.
 

The Somail program

The Somail program is written like a viewer for the .som format. This program is associated with the .som-format, so that if you double-click on a .som-file from the Explorer (File Manager), it will launch your email client and show the email in it.

When the Somail program is activated with a .som-file as a parameter, the following happens:
1. The program reads the file and creates what we call a MAPI-structure (This is perhaps more relevant to the programmer.)
2. The program logs on to the mail system, launches the email client (which must be SMAPI-compliant ) and shows the email in it.

If the program is started without a parameter, it will associate itself with the .som-extension.

This is the program SuperOffice starts when you open an email from it. In other words: With this program, SuperOffice has the same approach to emails as it has to any other document format.

If the .som-file contains a "flag=1"-directive, this means that the email has not been saved by the Somagate program and a dialog explaining this to the user will be shown.

The Somagate program
The Somagate program is the program that receives a copy of all emails sent out and stores them in the SuperOffice archive.

Somagate listens for incoming email. When such an email comes into Somagate's inbox, Somagate will read it and look for the tag ., which now has been replaced by something that looks like this: [RM\2001.1\SUPERO-OUTGO-TEST]. This means that Somagate will look for a .som file placed under <archivepath\rm\2001.1\supero-outgo-test.som>. If the file isn't found, Somagate will ignore the email. If the file is found, Somagate will save the email as a file with the same name. In other words: It will overwrite the original file.</archivepath\rm\2001.1\supero-outgo-test.som>

Somagate has it's own .ini-file (Somagate.ini). This file is always located in the same directory as Somagate itself, unless Somagate is installed in the same directory as SuperOffice. Then Somagate will use the superof4.ini file instead.

There's a lot more to say about Somagate, but that will be discussed under "Install SuperOffice Mail Gateway".

See Also