read-gmail-cg-lib

1. Introduction

The purpose of this component is to obtain a list of emails from a specific Gmail account and filter those emails with different parameters to obtain only the desired emails either by status or by date range. This Component also is using an oauth2 authentication where it needs a 3 specific parameters to create de authentication with de Gmail server.

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-gmail-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. xoauth2: is used to create the authentication with oauth2 on Gmail server.

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-gmail-cg-lib, npm i read-gmail-cg-lib or yarn install read-gmail-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.
  • 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.
  • clientId(required): This parameter is using to know the id of the application that was registered in the Google site APIs and services.
  • clientSecret(required): This parameter is the password for the application that was registered in the Google site APIs and services.
  • refreshToken(required): A refresh token allows your application to obtain new access tokens.

• 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":"**************@6delta.com",
      "host":"imap.gmail.com",
      "port":993,
      "status":"ALL",
      "startDate":"02/02/2022",
      "endDate":"02/02/2022",
      "dateFormat":"es-MX",
      "timeZone":"America/Los_Angeles",
      "clientId": "636278275583-*********************joq.apps.googleusercontent.com",
      "clientSecret": "G************************S8fs",
      "refreshToken": "1******************************************************7gCE"
             
  }
]

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": "Upcoming Webinar | What to Expect from PPM in 2022",
      "from": [
          {
              "address": "*****@apqc.org",
              "name": "APQC"
          }
      ],
      "to": [
          {
              "address": "***********@6delta.com",
              "name": ""
          }
      ],
      "text": "Hi Jafet,\n\nDon’t forget to join <https://go.apqc.org/MTU5LU9WSi0zMjIAAAGCWuOrVAklz9JTzEgeyRHXS7vEJtDYrigiGfTASNjqJnXo4klFkan9Sa2gyH6maPmAoEHlYJA=> APQC’s Holly Lyke-Ho-Gland as she shares the results of APQC’s2022 priorities and challenges survey and discusses best practices to helpyou and your organization address them.\n\nAttendees of this webinar will learn about:\n\n\n\n\t- top challenges in key topic areas,\n\t- practical tips and resources currently available,\n\t- making smart decisions around technology and BPM efforts,\n\t- and what research to expect in 2022.\n\n\n\nDate/Time: February 3, 2022&nbsp;| 11:00 a.m.&nbsp;US Central\nCheck your local time: <a href= \"https://go.apqc.org/MTU5LU9WSi0zMjIAAAGCWuOrVDupptnnQmiUNHdUNiuYD11O8GJyk4ANTwaTcW5sEiyq3K9C4Iv3YFPMeFyD7jNlzjA=\" target=\"_blank\" id=\"\" >https://everytimezone.com/s/f7523cc4</a>\n\n\nRegister now: pages.apqc.org/PPM-WhatToExpectIn2022.html <https://go.apqc.org/MTU5LU9WSi0zMjIAAAGCWuOrVAklz9JTzEgeyRHXS7vEJtDYrigiGfTASNjqJnXo4klFkan9Sa2gyH6maPmAoEHlYJA=>\n\n\nCan't Attend Live? We understand that not everyone can join our webinars live whether it be scheduling conflicts or timezone issues, so we are sure to send all registrants links to the slides and recording after the session, regardless of attendance. So register today <https://go.apqc.org/MTU5LU9WSi0zMjIAAAGCWuOrVAklz9JTzEgeyRHXS7vEJtDYrigiGfTASNjqJnXo4klFkan9Sa2gyH6maPmAoEHlYJA=> to get your links via email!\n\nThis email was sent to [email protected]. If you wish to update your email preferences, click here: http://pages.apqc.org/EmailPreferences.html\n",
      "date": "2/2/2022",
      "attachments": null
  },
  {
      "subject": "Prepare Today for Tomorrow’s Privacy Landscape",
      "from": [
          {
              "address": "*****@em.isaca.org",
              "name": "ISACA"
          }
      ],
      "to": [
          {
              "address": "***********@6delta.com",
              "name": ""
          }
      ],
      "text": "\n \n \n\n \nhttps://view.em.isaca.org/?qs=883c1ac3042432be61c7a864413fed8c7abfffb7a7560dc804d88514ce1615d8daf246aeb773347807294610ca7ca320088d8a28599155941ae53eed64bb4f416c9fe042e54661a02ecfff3486f2a234 \nRead Online \n\n\n \n \n\n \nhttps://click.em.isaca.org/?qs=, and services are not affiliated with CSX Corporation or its subsidiaries, including CSX Transportation, Inc.\n\n\n\n \n \n\n\n \n \n\n",
      "date": "2/2/2022",
      "attachments": null
  }
]