README.md

# Priority-Inbox Module

The priority-inbox is a maven java projet. This module allows to assign to an email a category (**IMPORTANT, TO_READ or NOTIFICATION**) and a score. The priority-inbox is based on a set of generic rules.

The tools is a rest-api that compute the category and a score from a email json file. In average, the service is able to process 37 emails/second {min 1,18/second;max 1000/second}(result obtained by processing 7768 emails).

### Supported categories

 1. **IMPORTANT**: is returned if the email is important. **15 generic rules** are implemented to indicate if an email is important or not. For instance, we analyse the signature of the email. An email will be considered important if its sender (from) is the CEO of a company or a Director of a Department. An email is important if the body contains many thread (many replies) or many forwards. 
 3. **NOTIFICATION**: is returned if the email is a notification email. For instance a chat notification, a social media notification or each email with a not-reply email.
 4. **TO_READ**: if the email is not **IMPORTANT** and not a **NOTIFICATION**

### First results
A small dataset of **706** emails was annotated manually (**310** important emails, **321** notification emails and **75** to_read email) was created to test this approach. 
Remember that this AI approach are not based on Machine Learning but only on generic rules to compute a priority for an email.

**The next table resume the obtained results:**

| Email category | Precision | Recall | Fmeasure |
| -------- | -------- | -------- | -------- |
| Important   | 84.61%   | 78.06%   | 81.20%   |
| To_Read   | 34.43%   | 69.33%   | 46.01%   |
| Notification   | 99.62%   | 83.48%   | 90.84%   |
  

# Running the service with Docker

## Building the image
```
wget https://ci.linagora.com/zsellami/priority-inbox/raw/master/Dockerfile

docker build -t demo:priorityInbox .
```
## Building a storage volume for data model
**Use this command to create a storage space for data model**

```
docker volume create volume_name
```

**if you want to delete the volume use the next command**

```
docker volume rm volume_name
```

## Running the image
**Before running the image**. Use the next command to get the full path for the docker storage volume:
```
docker volume inspect volume_name
```

**The image expose the port 9991 with the IP 0.0.0.0 .**  To run the service on a host port do the next instruction:
```
docker run --volume volume_storage_path:/priority-inbox/priorityInbox/models/ -it -p 5551:9991 demo:priorityInbox
```
## Calling the service

### Get email type and score service
```
curl  -X POST 'http://0.0.0.0:5551/rest/priorityinbox/parsejson' -F "file=@/path/to/email.json"
```
Sample of json file:

**Note that** the fields **user**, **alternativeAddress**, **from** and at least one of **to**, **cc** or **bcc** are required.
 1. **user** is the name of the INBOX user. For instance Jhon Doe.
 2. **alternativeAddress** is the differents email address for the INBOX. For instance jhon.doe@test.com or jdoe@test.com or doe@test.com.
 
**Note that** the field **emailFolder** is the folder in which the email is located. By default, please fill the string "**INBOX**"


```
{
  "messageId" : "messageId",
  "from" : {
    "address" : "from@test.com",
    "personal" : "first_name last_name"
   },
  "to" : [ {
    "address" : "to1@test.com",
    "personal" : "first_name last_name of to1"
   } ],
  "cc" : [ {
    "address" : "cc1@test.com",
    "personal" : null
    }, {
    "address" : "cc2@test.com",
    "personal" : "first_name last_name of cc2"
    }, {
    "address" : "cc3@test.com",
    "personal" : "first_name last_name of cc3"
   } ],
  "bcc" : [ ],
  "Received" : "Mon, 28 Jan 2019 07:56:43 +0000",
  "Date" : "Mon, 28 Jan 2019 07:56:43 +0000",
  "in-Reply-To" : "messageId_in_reply_to",
  "subject" : "IMPORTANT: Testing The Priority Inbox",
  "body" : "\nDear, \n\n this a test of the priority inbox\n regards,\nfirst_name last_name\nDirector Tester",
  "attachments" : [{
    "file_size" : "243534",
    "content_name" : "presentation.pdf",
    "content_type" : "APPLICATION/PDF"
    }, {
    "file_size": "243534",
    "content_name" : "APPLICATION/PDF",
    "content_type" : "performance.pdf"
    }],
  "emailFolder" : "INBOX",
  "user" : "first_name last_name of to1",
  "alternativeAddress" : [ "t1@test.com", "first_name.last_name@test.com" ],
  "X-Spam-Flag" : "NO"
}
```
Expected result:
```
{  
"category" : "IMPORTANT",  
"score" : 14.916666666666668  
}
```