read-email-cg-lib

1. Introduction

This code has the objective of obtain the emails from the mailbox of a mail server account (like gmail, Outlook or Yahoo) through some parameters to perform the search, and take the data of the emails and format them so that they are readable for the user.

This library is useful to be implemented as a OIH based component to be executed into the N3xGen Portal. This components can be developed by their owners to get a specific list of emails from a specific account to display from the component.

Within "read-email-cg-lib" three additional libraries are used: imap: used to connect to the mail server through the IMAP protocol, which must be previously configured if the mail server needs it and is also used to search for mail through the parameters specified. mailparser: it is used to format the result of the "imap" library to make it easier the interpretation of the data. utils-nxg-cg: is used to print the necessary logs and other common tools.

As final result is a JSON object with the principal data of the email, if the email has attachments the files are going to be included as base64 encodig.

2. Methods explanation

2.1. emailProcess

The library can be installed from npm page with the next:

npm install read-email-cg-lib, npm i read-email-cg-lib or yarn install read-email-cg-lib

This method searches for emails on a specific email server, the parameters that were defined are the ones that are taken to create the connection with the server and to search within an email account.

3. Argument and result explanation

• Arguments: The only and main method needs a list of parameters, some are mandatory and others are optional. The next are all the parameters listed with their description:

  • user (required): User to connect to the mail server.
  • password (required): Password to connect to the mail server.
  • host (required): Host to connect to the mail server.
  • port (required): Port to connect to the mail server.
  • status (required): This is a list of mail status that can be used to filter between all the emails in the inbox.
    • 'ALL' - All messages.
    • 'ANSWERED' - Messages with the Answered flag set.
    • 'DELETED' - Messages with the Deleted flag set.
    • 'DRAFT' - Messages with the Draft flag set.
    • 'FLAGGED' - Messages with the Flagged flag set.
    • 'NEW' - Messages that have the Recent flag set but not the Seen flag yet.
    • 'SEEN' - Messages that have the Seen flag set.
    • 'RECENT' - Messages that have the Recent flag set.
    • 'OLD' - Messages that do not have the Recent flag set. This is functionally equivalent to "!RECENT" (as opposed to "!NEW").
    • 'UNANSWERED'- Messages that do not have the Answered flag set.
    • 'UNDELETED' - Messages that do not have the Deleted flag set.
    • 'UNDRAFT' - Messages that do not have the Draft flag set.
    • 'UNFLAGGED' - Messages that do not have the Flagged flag set.
    • 'UNSEEN' - Messages that do not have the Seen flag set.
  • startDate (required): This set a start date to filter the search of emails.
  • endDate (required): This set a end date to filter the search of emails.
  • dateFormat (required): This parameters is used to define the format of the date according with the country, there are three options: "en-US" for Unites States format, "en-CA" for Canada format and "es-MX" for México format.
  • sortDate (no required): Parameter to sort the emails by date, there are just 2 options, "desc" for descending taking first the newest "asc" for ascending taking first the oldest."
  • timeZone (no required): This parameter allows to set the time zone that is required to be used in the process of the library. It should be specified a time zone value from the TZ database, the complet list of the possible time zones are available in this url https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. If a time zone is not defined, bye default the library will set the same time zone as the server in which the library runs.

• Result: As a result of the email search, the library creates an object array with the email data, where each object represents an email with its main attributes as shown in the next image:

note: the library is making an evaluation about this result in the order that the result has a JSON structure to be valid.

• subject: the subject of the email.
• from: Is an object that contains the address and name attributes:
  • address: The email account of the sender of the mail.
  • name: The full name of the sender of the mail.
• to: Is an object that contains addres and name attibutes:
  • address: The email account of the addressee of the mail.
  • name: The full name of the addressee of the mail.
• text: The message in the body of the email.
• date: The date when the mail was received.
• attachments: An array of objects that contais the list of attachments (if they exist in the mail). This array has the next attributes:
  • filename: The name of the attachment file.
  • contentType: The content type of the attachment file.
  • content: The content of the attachment file in base64 encoding.

3. Examples

This part will shows some examples on how to send the input parameters to the library and what its result would be. In the next object is a valid object with full parameters that can be set to the library:

{
    "user":"[email protected]",
    "password":"1234",
    "host":"imap.gmail.com",
    "port":993,
    "status":"ALL",
    "startDate":"09/09/2022",
    "endDate":"09/10/2022",
    "dateFormat":"es-MX",
    "sortDate":"desc"
}

In this case it is used a gmail account to get the all ("ALL") the emails from September 9th to September 10th, the date is set to Mexico format ("es-MX") and sorted in descending order ("desc") to get the newest first, the result should look like as follows:

[
    {
        "subject": "🇲🇽 ¡Venta de Independencia! En compras en cimaco.com 💻 Hasta 20% de descuento además hasta 18 Mensualidades sin Intereses 🥳",
        "from": [
            {
                "address": "[email protected]",
                "name": "Promociones Cimaco"
            }
        ],
        "to": [
            {
                "address": "[email protected]",
                "name": ""
            }
        ],
        "text": " En el caso de que no puedas visualizar este correo \nhttps://view.S6.exacttarget.com/?qs=5d56adc625948a3fe309f9eef3fc2b16ca207a4090b6ee2a97e826b8bdd9c553d92bfa00b43a148077e45213d41162f54f716aaaf166e0cedfa3930b44791d106b4a33ba63bf98b8 \n da un click aquí. \nPABLO,\n\n\nhttps://cl.s6.exct.net/?qs=f9986b09318b64f8e8a9f901e37f1d512184c3ea01a216bb54f352d6c1b9983e7c3e15b4d218124586b2d914b46c4169 \n\n\n\nAtención a Clientes: 800 224 6226\n\n800 A CIMACO\nCompañía Comercial Cimaco, S.A. de C.V.\n\nhttps://cl.s6.exct.net/?qs=f9986b09318b64f829b0795cf5019fe973fcf348fe30be39a2b2c20e9143cf3275e104ca1973f1054bb467ea13d812e1 \nHidalgo #399 Pte. Col Centro, C.P. 27000 Torreon Coahuila, Mexico. \n\n *No responder a este correo, es solo de envio.\n\nhttps://cl.S6.exct.net/unsub_center.aspx?qs=218508d0ef6920a6c2282e2e84fb97f415b64a42acfce668070f01d43a40348d5cd737d85d0653f9adff63bd1b1627ee0376ee57eb4d4b6e8a97a80b3522cd44 \nNo deseo recibir más promociones\n\n\n",
        "date": "10/09/2022",
        "attachments": null
    },
    {
        "subject": "Prueba 1",
        "from": [
            {
                "address": "[email protected]",
                "name": "pablo perez"
            }
        ],
        "to": [
            {
                "address": "[email protected]",
                "name": ""
            }
        ],
        "text": "Mensaje de prueba para el correo\n\nEnviado desde Correo<https://go.microsoft.com/fwlink/?LinkId=550986> para Windows\n\n",
        "date": "09/09/2022",
        "attachments": null
    }
]

In this example the sort is "desc" descending so first the mail of September 10th is listed. In this other example the sort parameter is set to "asc" ascending:

{
    "user":"[email protected]",
    "password":"1234",
    "host":"imap.gmail.com",
    "port":993,
    "status":"ALL",
    "startDate":"09/09/2022",
    "endDate":"09/10/2022",
    "dateFormat":"es-MX",
    "sortDate":"asc",
    "timeZone":"America/Los_Angeles"
}

So the result is going to be something like this:

[
    {
        "subject": "Prueba 1",
        "from": [
            {
                "address": "[email protected]",
                "name": "pablo perez"
            }
        ],
        "to": [
            {
                "address": "[email protected]",
                "name": ""
            }
        ],
        "text": "Mensaje de prueba para el correo\n\nEnviado desde Correo<https://go.microsoft.com/fwlink/?LinkId=550986> para Windows\n\n",
        "date": "09/09/2022",
        "attachments": null
    },
    {
        "subject": "🇲🇽 ¡Venta de Independencia! En compras en cimaco.com 💻 Hasta 20% de descuento además hasta 18 Mensualidades sin Intereses 🥳",
        "from": [
            {
                "address": "[email protected]",
                "name": "Promociones Cimaco"
            }
        ],
        "to": [
            {
                "address": "[email protected]",
                "name": ""
            }
        ],
        "text": " En el caso de que no puedas visualizar este correo \nhttps://view.S6.exacttarget.com/?qs=5d56adc625948a3fe309f9eef3fc2b16ca207a4090b6ee2a97e826b8bdd9c553d92bfa00b43a148077e45213d41162f54f716aaaf166e0cedfa3930b44791d106b4a33ba63bf98b8 \n da un click aquí. \npablo,\n\n\nhttps://cl.s6.exct.net/?qs=f9986b09318b64f8e8a9f901e37f1d512184c3ea01a216bb54f352d6c1b9983e7c3e15b4d218124586b2d914b46c4169 \n\n\n\nAtención a Clientes: 800 224 6226\n\n800 A CIMACO\nCompañía Comercial Cimaco, S.A. de C.V.\n\nhttps://cl.s6.exct.net/?qs=f9986b09318b64f829b0795cf5019fe973fcf348fe30be39a2b2c20e9143cf3275e104ca1973f1054bb467ea13d812e1 \nHidalgo #399 Pte. Col Centro, C.P. 27000 Torreon Coahuila, Mexico. \n\n *No responder a este correo, es solo de envio.\n\nhttps://cl.S6.exct.net/unsub_center.aspx?qs=218508d0ef6920a6c2282e2e84fb97f415b64a42acfce668070f01d43a40348d5cd737d85d0653f9adff63bd1b1627ee0376ee57eb4d4b6e8a97a80b3522cd44 \nNo deseo recibir m&aacute;s promociones\n\n\n",
        "date": "10/09/2022",
        "attachments": null
    }
]

Thaking first the September 9th (the oldest).