Applications intro/overview

OnionMail supports the application bot interface to create virual mail addresses connected to applications interface. All addresses of bots must have a local part end with .app suffix.

The applications will launched via shell (fixed command line). OnionMail will connect to the application via STDIN/STDOUT.
All error in STDERR will raise an Exception with SMTP error reply. If the first line of error starts with character @ follwed by a SMTP code and message, it will forwarded as SMTP error.

There thtee way to build an OnionMail's application:

• SMTP Mode:
  The protocol is SMTP and OnionMail will comunicate with application in a SMTP session.
  All text output (STDOUT) will sent to the sender as body of the message.
  
• Batch mode:
  OnionMail send all headers to the application and wait for end of stream.
  All text output (STDOUT) will readed as headers and the body of the message, then will send to the sender.
  
• Application Mode:
  OnionMail send all headers to the application and wait a line to get the return status.
  All text output (STDOUT) will sent to the sender as body of the message.

The message must be ended by a line with only a dot "." (like SMTP session).

Application definition and parameters

The applications must definited into the servers.conf file into the server's section.
(If you whant to share application with other servers you can create another configuration file and use the @include command instead).

An application is defined via configuration files (.app.conf) and Application command.
Example of Application definition in servers.conf:

Application myApp.app.conf

All parameters are definited into the application file:

• Name:
  This define the local part of mail address of an application.
• Charset:
  Set the characters encodings of application (only for return messages).
  
• Cmd:
  Define the shell command to run the external application.
• MaxMsgLength:
  Define the maximum size of incoming messages.
• MaxReLength:
  Define the maximum size of resply messages.
• Base64:
  Enable the base64 encoding or return message. (use yes or no).
• Req:
  Check if the required file exists.
• RunMode:
  Define the application type: SMTP, BATCH, APP.
• AccessMode:
  Define the access permissions to application.
  This check only the sender address. You can use more AccessMode commands to enable/disable sender types.
  The available mode are:
• TOR:
  Only messages from TOR network.
• INTERNET:
  Only messages from the Internet.
  
• SYSOP:
  Only sysop users.
• USER:
  Only local user.

Application example

How to create a "Hello World" application.

In the file srvers.conf into the server's section, place this line:

Application hello.app.conf

Content of the file hello.app.conf:

name       hello.app
charset    ISO-8859-1
cmd        cat hello.txt
base64     true
RunMode    SMTP

Content of the file hello.txt:

220 Ok

220 Ok

220 Ok

220 Ok

312 Ok
250 Id=None Ok

Subject: Hello World

Hello World ;)

.

Don't forget the point at the end of file:

CR LF . CR LF

The output must have CR + LF

Special headers

Application Mode:
From: Is replaced with MAIL FROM (real sender).

Batch Mode:
Envelope-From: Is replaced with MAIL FROM (real sender).
X-Server: It contains the server's nick name (use this for shared applications).

Reply Messages:
X-Generated: server app
This header is added to the reply messages.

Best practice

A good application must select command from the subject of the message. The subject commands can be used as application/sections or commands.
A good practice is an implementation of RULEZ command of application with help message reply.