General specifications of ProMail implementation & upgrade. Merging ...

General specifications of ProMail implementation & upgrade. Merging of all old spec.

ProMail EAC Software

Nicolas Korboulewsky

ProMail Global spec

VERSION: 1.0 DATE: 18/01/2017

Document version : Edition Date : Language : Origin : Redactor : Ref : State :

V 1.0.0 15/02/16 EN Création NKY PROMAIL-S. Draft

REVISION HISTORY:

Date 18/01/2017

Version

Description Merging of all sources to make a coherent documentation.

Authors Nicolas Korboulewsky

SUBJECT: This document is a merge of all sources about ProMail it provides documentations of the features implemented in ProMail EAC. SUMMARY : UI Features ......................................................................................................................................................................................... 3 ProMail VScript implementation ................................................................................................................................................ 10 EAC Object ................................................................................................................................................................................ 10 Preparing the EAC Message .............................................................................................................................................. 10 Sending the EAC message .................................................................................................................................................. 10 Building EACViewer URL. .................................................................................................................................................. 11 ProMail application object ...................................................................................................................................................... 12 Accessing current objects .................................................................................................................................................. 12 Accessing command that called mail composer ........................................................................................................... 12 Connection object ............................................................................................................................................................... 12 Label object ............................................................................................................................................................................ 13 Mailbox Object .......................................................................................................................................................................... 15 Creating mailbox .................................................................................................................................................................. 15 Accessing existing mailboxes ............................................................................................................................................. 15 Deleting mailboxes ............................................................................................................................................................... 15 Sending messages.................................................................................................................................................................. 16

AppInMail R&D Tél. +359 89 54 24 164

http://www.appinmail.io [email protected]

ProMail Global spec

VERSION: 1.0 DATE: 18/01/2017

Archive object ............................................................................................................................................................................ 16 Creating archive .................................................................................................................................................................... 16 Accessing existing archives ................................................................................................................................................ 16 Deleting archives .................................................................................................................................................................. 17 Number of messages in archive ........................................................................................................................................ 18 Message object ........................................................................................................................................................................... 18 Accessing existing messages .............................................................................................................................................. 18 Modifying message attributes ............................................................................................................................................ 18 Message object attributes................................................................................................................................................... 19 Message object methods .................................................................................................................................................... 19 Managing default mail composers ......................................................................................................................................... 20 Search Query (/!\ not implemented) .................................................................................................................................... 21 Events ........................................................................................................................................................................................... 21 Incoming e-mail ..................................................................................................................................................................... 21 Moving e-mail to archive .................................................................................................................................................... 22 Opening e-mail ...................................................................................................................................................................... 22

AppInMail R&D Tél. +359 89 54 24 164


ProMail Global spec

VERSION: 1.0 DATE: 18/01/2017

UI Features The ProMail software is a Web based client that enable to read & make email. The last version implements the EAC technology and all side features of it. The general overview of it is shown on Figure 1.

Figure 1 : General Windows

Feature:

Email composer The first major difference and advantage of ProMail against the other Email client is to provide a customizable mail composer. The behaviour of it is following:  A list is defined when you click on the arrow.  This list is composed of an icon & a name.  The icon is this one of the Macro set with a type: [Button macro] & location: [Mail composer]  A click on the item launch the Macro and set this Macro as default. After a macro is chosen this one is set as default choice, a simple click on it will relaunch the same macro.

Feature:

Multi inbox management ProMail manage many email account, to allow a quick view to the unread email this section present a list of rounded rectangle with the amount of unread email of this mailbox. The color is this one chosen during the creation of the mailbox.

AppInMail R&D Tél. +359 89 54 24 164


ProMail Global spec

VERSION: 1.0 DATE: 18/01/2017

Feature

Inbox selector This listbox enable the user to select the active mailbox. The 3 dots button is a sub menu with the following options: 

Feature

Mailbox archive management There is 4 unmanageable MailBox :  Inbox  Outbox  Draft  Deleted The others mailbox are added by the user or plug-in. This mailbox can be shared with virtual mailbox container (it means they are not attached to some email address).

Feature

Mail selector

Feature

Delete button The email composer is based on

Feature

Search The email composer is based on

Feature

Mail item list

AppInMail R&D Tél. +359 89 54 24 164


ProMail Global spec

VERSION: 1.0 DATE: 18/01/2017

The items list proposed by ProMail is fully configurable with VDOM XML template. It has a basic structure like this one shown but it can be replaced by other VDOM XML found in section of WHOLE XML Envelope. The item list is dynamically loaded & a dynamic refresh mechanism is used when the email list is changed.

Feature

Mail list item Property of the Mail list item is defined by METADATA section if exist as shown here : … In this section if exist we will have a list of Tags for this email & some VDOM XML to present the result. If the item is interactive, it will need a Plug-in to process event & this will be given by PLUGIN section.

Feature

Email actions buttons This is the basic function of standard email, this functions are pointless with EAC email & should not be shown.

AppInMail R&D Tél. +359 89 54 24 164


ProMail Global spec

VERSION: 1.0 DATE: 18/01/2017

Feature

Standard email panel

The standard panel is splited in 3 parts : 1. Global data about the email, from/to, the date, the subject & the list of tags 2. The Body of the email rendered as filtered HTML content 3. Attached documents

AppInMail R&D Tél. +359 89 54 24 164


ProMail Global spec

VERSION: 1.0 DATE: 18/01/2017

Feature

Feature

Feature

Standard email general information panel

Standard email body panel

Standard email attachment panel

AppInMail R&D Tél. +359 89 54 24 164


ProMail Global spec

VERSION: 1.0 DATE: 18/01/2017

Feature

EAC Email panel

The EAC panel is contain only 2 panel the general info about the email & the EAC content rendered.

Feature

EAC email general information panel

The general panel shows additional information about the origin of the email and the fact this email is EAC by showing the logo.

AppInMail R&D Tél. +359 89 54 24 164


ProMail Global spec

Feature

VERSION: 1.0 DATE: 18/01/2017

EAC email body panel

The main panel shows the render content of the EAC email. This content is rendered in HTML+JS inside an EAC container that transmit the events to the Business Logic of the application attached to this email.

Feature

Tabs

Tabs are used to process to the content of usual email with some Plug-In that will output some EAC rendered content to it shown then in the main panel.

AppInMail R&D Tél. +359 89 54 24 164


ProMail Global spec

VERSION: 1.0 DATE: 18/01/2017

ProMail VScript implementation EAC Object Preparing the EAC Message The EAC object is a class to build & send valid EAC Message. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44

Set e = new EAC e.dynamic = false e.auth = "external" e.session_token = "123" e.login_container = "1-2-3-4" e.login_method = "login222" e.get_container = "1-2-3-4" e.get_method = "get222" e.get_data = "getdata" e.post_container = "1-2-3-4" e.post_method = "post222" e.post_data = "postdata" e.api_server = "127.0.0.1" e.app_id = "5-6-7-8" e.events_data = "events" e.vdomxml_data = "vdomxml" e.item_plugin = "itemplugin" e.item_vdomxml = "itemvdomxml" e.add_tag("tag1", "ff0000") e.add_tag("tag2", "00ff00") e.remove_tag("tag2") e.eac_token = "12345" e.eac_method = "new" e.get_wholexml() e.set_events(events)

' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' '

true/false whether it's dynamic content (boolean) internal/external authentication (string) session token (string) ID of the container where the login method is (string) name of the login method (string) ID of the container where to call the method to get data (string) name of the method to get data (string) data to be sent as pattern for GET request (string) ID of the container where to call the method to post data (string) name of the method to post data (string) data to be sent as pattern for POST request (string) URL of backend server to handle EAC business logic (string) ID of the VDOM application running the business logic (string) JSON structure that represents events (string) XML that represents the VDOM XML for this object (string) ID of the plugin to process the events of interactive mail list item (string) custom VDOM XML to render mail list item for this email (string) method to add tag with name and color (strings)

' ' ' ' ' ' '

method to remove tag by name EAC token (string) EAC method (string, new/update/delete) return composed XML as string method to set events data, accepts JSON string or dictionary

Most of the methods and properties are speaking themselves,

Sending the EAC message 1

e.send(ProMail.selected_mailbox, , "", "", "test subject", "Hello", attachments)

2

AppInMail R&D Tél. +359 89 54 24 164


ProMail Global spec

VERSION: 1.0 DATE: 18/01/2017

ProMail.selected_mailbox is currently selected mailbox, message will be sent using that mailbox SMTP server if the mailbox is not virtual. Parameter 3 may contain the list of recipients of message copy. Parameter 6 is a string to be used as alternative message body for email clients that don't support EAC. The last parameter is a Dictionary object containing attachments of the message, if any. Key is attachment file name and value is the content.

Building EACViewer URL. The EAC object has method to build EACViewer URL based on its filled properties. 1

e.get_eacviewer_url(host, email)

Returns composed EACViewer URL using previously set properties and method parameters. host is the hostname that the EACViewer URL will target (usually it’s the host name of the current system). email should be the appinmail email address of the user who will get this EACViewer URL.

AppInMail R&D Tél. +359 89 54 24 164


ProMail Global spec

VERSION: 1.0 DATE: 18/01/2017

ProMail application object ProMail software is built as an object oriented structure allowing to interact with it. Here the description of what is possible.

Accessing current objects This method returns what the current user is using on the UI. 1

ProMail.selected_mailbox

This is the object that represents currently selected mailbox. 1

ProMail.selected_mailbox

This is the object that represents currently selected archive. 1

ProMail.selected_mail

This is the object that represents currently selected message.

Accessing command that called mail composer 1

ProMail.mailcomposer_command

This is the string that contains command that initiated the mail composer, one of: "new", "reply", "reply_all", "forward".

Connection object Creating a new connection 1

Set conn = ProMail.create_connection("{""name"":""conn1"", ""pop3_host"":""10.40.0.10"", ""pop3_port"":""100"", ""pop3_secure"":""none"", ""smtp_host"":""10.40.0.11"", ""smtp_port"":""101"", ""smtp_secure"":""starttls"", ""imap_host"":""10.40.0.12"", ""imap_port"":""102"", ""imap_secure"":""ssl""}")

This creates connection with specified settings. Settings should be passed as a JSON formatted string or a dictionary object. 1 2 3 4 5 6 7 8 9 10 11 12

Set conn = ProMail.create_connection() conn.name = "myconnection" conn.pop3.host = "1.2.3.4" conn.pop3.port = 100 conn.pop3.secure = "none" conn.smtp.host = "1.2.3.5" conn.smtp.port = 101 conn.smtp.secure = "starttls" conn.imap.host = "1.2.3.6" conn.imap.port = 102 conn.imap.secure = "ssl" conn.save()

AppInMail R&D Tél. +359 89 54 24 164


ProMail Global spec

VERSION: 1.0 DATE: 18/01/2017

This is another way of creating a connection. First an empty object is created, then all properties are set and the object is saved.

Accessing existing connections 1

Set c = ProMail.get_connection("conn1")

This returns the connection object by name. 1 2 3 4

connections = ProMail.get_connections() for each x in connections logger(x.name) next

This enumerates all existing connections.

Deleting connections 1 2 3 4

Set c = ProMail.get_connection("conn1") c.remove() 'or ProMail.remove_connection("conn1")

2 methods to delete a connection.

Label object Creating label 1

Set label = ProMail.create_label("{""name"":""my_label"", ""color"":""0000ff"", ""text_color"":""ffffff""}")

This creates a label with specified name, color and text color. Settings should be passed as a JSON formatted string or a dictionary object. 1 2 3 4 5

Set label = ProMail.create_label() label.name = "my_label" label.color = "0000ff" label.text_color = "ffffff" label.save()

This is another way of creating a label. First an empty object is created, then all properties are set and the object is saved.

Accessing existing labels 1

Set label = ProMail.get_label("label1")

This returns the label object by name.

AppInMail R&D Tél. +359 89 54 24 164


ProMail Global spec

1 2 3 4 5

VERSION: 1.0 DATE: 18/01/2017

Try Set label = ProMail.get_label("label1") Catch logger("Label not found") End Try

The same sample as above but with error handling. It handles the case when the label with specified name doesn't exist. 1 2 3 4 5

labels = ProMail.get_labels() for each x in labels logger(x.name) next

Deleting labels 1 2

Set l = ProMail.get_label("label1") l.remove()

This removes the label. 1

ProMail.remove_label("label1")

This does the same but without querying the label object. Label object has messages attribute that contains the list of Message objects representing messages associated with the label. 1 2 3 4 5

Set label = ProMail.get_label("abc") for each m in label.messages logger(m.subject) next

This way one can enumerate all messages associated with the label. This sample implies label with name abc exists.

AppInMail R&D Tél. +359 89 54 24 164


ProMail Global spec

VERSION: 1.0 DATE: 18/01/2017

Mailbox Object Creating mailbox 1

Set box = ProMail.create_mailbox("{""name"":""NewBox"", ""color"":""00ff00""}")

This creates a virtual mailbox with specified name and color. Settings should be passed as a JSON formatted string or a dictionary object. 1

Set box = ProMail.create_mailbox("{""name"":""Box2"", ""color"":""0000ff"", ""login"":""aa"", ""password"":""bb"", ""connection"":""" & conn.name & """}")

This creates a 'real' mailbox with specified login, password and connection. This sample implies conn is a Connection object like the one from the Creating connection section. 1 2 3 4 5 6 7 8

Set box = ProMail.create_mailbox() box.name = "mybox" box.connection = ProMail.get_connection("conn1") box.color = "ff00ff" box.login = "myloginname" box.password = "mypassword" box.save()

This is another way of creating a mailbox. First an empty object is created, then all properties are set and the object is saved. This sample implies the connection named conn1 exists.

Accessing existing mailboxes 1

Set m = ProMail.get_mailbox("box1")

This returns the mailbox object by name. 1 2 3 4 5

Try Set m = ProMail.get_mailbox("box1") Catch logger("Mailbox not found") End Try

The same sample as above but with error handling. It handles the case when the mailbox with specified name doesn't exist. 1 2 3 4 5

mailboxes = ProMail.get_mailboxes() for each x in mailboxes logger(x.name) next

This enumerates all existing mailboxes.

Deleting mailboxes AppInMail R&D Tél. +359 89 54 24 164


ProMail Global spec

1 2 3 4

VERSION: 1.0 DATE: 18/01/2017

Set m = ProMail.get_mailbox("box1") m.remove() 'or ProMail.remove_mailbox("box1")

These 2 ways removes the mailbox.

Sending messages Message can be sent with Mailbox object, in case it's not a virtual one. 1 2 3 4 5

attachments = Dictionary Set mailbox = ProMail.get_mailbox("box") mailbox.send_email(, "", "", "test subject", "Hello", attachments) 'suppose there is EAC object named e mailbox.send_eac_email(, "", "", "test subject", "Hello", attachments, e)

This sample gets mailbox named box and first sends a standard email and then an EAC email. This sample implies the non-virtual mailbox named box exists. Parameter 2 may contain the list of recipients of message copy. Parameter attachments may be filled with attachments of the message.

Archive object This VScript object represent the archive on left panel, there is built in Archives : inbox, outbox, draft, trash that actually are not shareable. The additional archives can be fully managed and shared.

Creating archive 1 2 3 4 5 6 7

Set mailbox = ProMail.get_mailbox("box") Set archive = mailbox.create_archive("{""name"":""my_archive""}") 'or Set mailbox = ProMail.get_mailbox("box") Set archive = mailbox.create_archive() archive.name = "my_archive" archive.save()

This creates an archive in mailbox box with specified name. Settings should be passed as a JSON formatted string or a dictionary object. This sample implies the mailbox named box exists.

Accessing existing archives 1 2 3 4 5 6 7 8

Set mailbox = ProMail.get_mailbox("box") Set archive = mailbox.get_archive("my_archive") 'or Set mailbox = ProMail.get_mailbox("box") archives = mailbox.get_archives() for each x in archives logger(x.name) next

This returns the mailbox object by name. This sample implies the mailbox named box exists.

AppInMail R&D Tél. +359 89 54 24 164


ProMail Global spec

VERSION: 1.0 DATE: 18/01/2017

Deleting archives 1 2 3 4 5 6

Set mailbox = ProMail.get_mailbox("box") mailbox.remove_archive("my_archive") 'or Set mailbox = ProMail.get_mailbox("box") Set archive = mailbox.get_archive("my_archive") archive.remove()

This removes the archive. This sample implies the mailbox named box and its archive named my_archive exist.

AppInMail R&D Tél. +359 89 54 24 164


ProMail Global spec

VERSION: 1.0 DATE: 18/01/2017

Number of messages in archive 1 2 3 4 5

Set mailbox = ProMail.get_mailbox("box") Set archive = mailbox.get_archive("my_archive") logger(archive.message_count) logger(archive.unread_message_count) logger(archive.urgent_message_count)

This sample shows total message count, unread message count and urgent message count of the archive. This sample implies the mailbox named box and its archive named my_archive exist.

Message object Accessing existing messages 1

archive.get_all_messages()

This returns the list of all messages in the archive. 1

archive.get_unread_messages()

This returns the list of unread messages in the archive. 1

archive.get_urgent_messages()

This returns the list of urgent messages in the archive. 1 2 3 4 5 6

Set mailbox = ProMail.get_mailbox("box") Set archive = mailbox.get_archive("my_archive") all_messages = archive.get_all_messages() for each m in all_messages logger(m.subject) next

This sample enumerates all messages of the archive and logs their subjects. This sample implies the mailbox named box and its archive named my_archive exist.

Modifying message attributes 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19

Set mailbox = ProMail.get_mailbox("box") Set archive = mailbox.get_archive("my_archive") all_messages = archive.get_all_messages() Set m = all_messages(0) m.subject = "New subject" m.sender.name = "new_sender" m.sender.email = "test@test" rc = m.recipients Set r = rc(0) r.name = "new_recipient" r.email = "test@test" att = m.attachments Set a = att(0) a.name = "new_attachment_name.txt" a.content = "Hi there!" m.save()

AppInMail R&D Tél. +359 89 54 24 164


ProMail Global spec

VERSION: 1.0 DATE: 18/01/2017

This sample gets the first message of the archive and modifies its subject, sender and first recipient. Then this sample gets the first attachment of the message and modifies its name and content. This sample implies the mailbox named box, its archive named my_archive and at least one message (that also has at least one attachment) exist.

Message object attributes 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24

message.subject message.body message.body_type message.preview_body message.sender message.sender.name message.sender.email message.recipients message.recipients_cc message.attachments message.labels message.datetime message.priority message.EAC

' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' '

read/write, message subject read/write, message body read/write, MIME type of message body read/write, text displayed as message preview in mail list read, Contact object representing message sender read/write, name field of the message sender Contact object read/write, email field of the message sender Contact object read, list of Contact objects representing message recipients read, list of Contact objects representing message copy recipients read, list of Attachment objects representing message attachments read, list of Label objects representing message labels read, message date and time read/write, message priority: '1' - high, '2' - normal, '3' - low read, message EAC object (empty for non-EAC messages)

Message object methods 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

message.create_recipient(name, email)

' ' message.remove_recipient(name, email) ' ' ' message.create_recipient_cc(name, email) ' ' message.remove_recipient_cc(name, email) ' ' ' ' message.create_attachment(name, content) ' message.remove_attachment(name) ' message.add_label(label) ' ' ' message.remove_label(label) ' '

add new recipient of the message remove message recipient, name and email parameters are optional add new recipient of the message copy remove message copy recipient, name and email parameters are optional create message attachment remove message attachment assign label to the message (label must be an existing Label object) unassign label from the message

AppInMail R&D Tél. +359 89 54 24 164


ProMail Global spec

VERSION: 1.0 DATE: 18/01/2017

Creating messages 1 2 3 4 5 6 7 8 9

Set mailbox = ProMail.get_mailbox("box") Set archive = mailbox.get_archive("my_archive") Set msg = archive.create_message() msg.subject = "This message was created by script" msg.body = "Hello" msg.sender.name = "Vasya" msg.sender.email = "vasya@mail" msg.create_recipient("Petya", "petya@mail") msg.save()

This creates a message in the archive. First a Message object is created with create_message method. Then all message properties are set and the object is saved. 1 2

msg.EAC.eac_token = "12345" msg.save()

This way one can modify EAC attributes of the message.

Deleting messages 1 2 3 4 5

Set mailbox = ProMail.get_mailbox("box") Set archive = mailbox.get_archive("my_archive") all_messages = archive.get_all_messages() Set msg = all_messages(0) msg.remove()

This removes the first message of the archive. This sample implies the mailbox named box, its archive named my_archive and at least one message there exist.

Copying and moving messages 1 2 3 4 5 6 7 8

Set mailbox = ProMail.get_mailbox("box") Set inbox = mailbox.get_archive("inbox") Set draft = mailbox.get_archive("draft") Set archive = mailbox.get_archive("my_archive") all_messages = archive.get_all_messages() Set msg = all_messages(0) msg.copy_to(inbox) msg.move_to(draft)

This sample gets the first message of the archive named my_archive and first copies it to the inbox archive and then moves it to the draft archive. This sample implies the mailbox named box, archives named my_archive, inbox, draft and at least one message in my_archive exist.

Managing default mail composers ProMail can store permanent settings for mail composers. These settings may contain identifiers of macros used for creating a new mail, for replying to an existing mail, for replying to all recipients of an existing mail, for forwarding an existing mail. The following functions can be used to create those settings.

AppInMail R&D Tél. +359 89 54 24 164


ProMail Global spec

1 2 3 4 5 6 7 8 9 10 11 12

VERSION: 1.0 DATE: 18/01/2017

' set default macro for creating a new email ProMail.set_default_composer("plugin_id", "macro_id") ' set default macro for replying to an existing email ProMail.set_default_reply("plugin_id", "macro_id") ' set default macro for replying to all recipients of an ' existing email ProMail.set_default_reply_all("plugin_id", "macro_id") ' set default macro for forwarding an existing email ProMail.set_default_forward("plugin_id", "macro_id")

All functions above accept the same parameters: identifiers of plugin and macro. Macros should examine ProMail.mailcomposer_command value to find out which action is expected. This value contains one of the following strings: "new", "reply", "reply_all", "forward". Macros may use attributes of current email which is accessible as ProMail.selected_mail.

Search Query (/!\ not implemented) 'Query fields 'search >> no meta search global search 'to >> to meta 'from >> from meta 'cc >> from cc 'cci >> from cci 'date >> ?Range of date 'subject>> in subject 'attachement >> true / false (if true search in attachement as well) 1 2 3 4 5 6 7 8 9 10 11 12

EmailsList.copyTo(mailbox,archive) EmailsList.moveTo(mailbox,archive) EmailsList.delete EmailsList.setTags(taglist) this one, array can be empty EmailsList.addTags(taglist) EmailsList.removeTags(taglist)

'>> '>> '>> '>>

copy all mail to a mailbox & archive move mail to a mailbox & archive delete all emails (taglist array of tags) replace tags list by

'>> Add Tags list to the current one '>> Remove from the list the tags list

EmailsList.getAllEmails() EmailsList.getUnreadEmails() EmailsList.getUrgentEmails() EmailsList.getByTags(taglist)

Events Event are generate by internal behaviour, here the list of the event internally supported.

Incoming e-mail The incoming email event is risen when a new email is fetched from an external mailbox server that ProMail is connected to. This event is attached to inbox of a mailbox object

AppInMail R&D Tél. +359 89 54 24 164


ProMail Global spec

1 2

event.email event.mailbox

VERSION: 1.0 DATE: 18/01/2017

'>> email object that represent the incoming one '>> mailbox object concerned by this event

Moving e-mail to archive This event appears when a user moves an email from one archive to an other. 1 2 3 4

event.email event.mailbox event.archive event.user

'>> '>> '>> '>>

email object that represent the incoming one mailbox object concerned by this event what is the archive which receive this email Object representing the user performing the operation

Opening e-mail This event appears when a user click on an item & want to read an email 1 2 3 4

event.email event.mailbox event.archive event.user

'>> '>> '>> '>>

email object that represent the incoming one mailbox object concerned by this event what is the archive which receive this email Object representing the user performing the operation

AppInMail R&D Tél. +359 89 54 24 164
