Email Plugin

The plugin provides functionality to interact with email servers over IMAPS protocol.

Installation

  1. Copy the below line to dependencies section of the project build.gradle file

    Example 1. build.gradle
    implementation(group: 'org.vividus', name: 'vividus-plugin-email', version: '0.5.12')

  2. If the project was imported to the IDE before adding new dependency, re-generate the configuration files for the used IDE and then refresh the project in the used IDE.

Properties

Required

  • email.server.<server-key>.username - defines email server username

  • email.server.<server-key>.password - defines email server password

  • email.server.<server-key>.properties.host - defines email server host, e.g. imap.gmail.com

  • email.server.<server-key>.properties.port - defines email server port, e.g. 993

Optional

  • email.imap.wait.duration - defines message polling duration from the email server, default value is PT30S

  • email.imap.wait.retry-times - defines a number of retries will be performed during polling duration, default value is 5

  • email.imap.folder - defines folder name to work with, default value is Inbox

Polling timeout that can be calculated by email.imap.wait.duration / email.imap.wait.retry-times must be not less than 5 seconds.

For IMAP configuration details see IMAP Properties. To use IMAP properties the mail.imap. prefix must be replaced with email.server.<server-key>.properties. e.g. mail.imap.timeout will become email.server.<server-key>.properties.timeout. The <server-key> is a logical name defining single server configuration and referred in steps.

Example 2. Configuration example: email.properties
# email server
email.server.gmail.username=bob
email.server.gmail.password=2kj34ndd
email.server.gmail.properties.host=imap.gmail.com
email.server.gmail.properties.port=993
email.server.gmail.properties.starttls.required=true
email.server.gmail.properties.usesocketchannels=true

# client
email.imap.wait.duration=PT15S
email.imap.wait.retry-times=3
email.imap.folder=Inbox

Steps

Fetch message from an email server

Fetches an email message from a server filtered by user-defined filters. If the message is found its text content parts are saved into indexed variables prefixed variableName parameter and part index, e.g. if the message contains two text parts, the first part will be saved under variableName[0] and the second under variableName[1].

When I fetch email message from `$serverKey` server filtered by $filters and save message content to $scopes variable `$variableName`

  • $serverKey - The server configuration to identify a server to fetch a message from.

  • $filters - The ExamplesTable with filters to be applied to emails to limit the resulting set. The table columns are:

    • parameter

      Name Description

      SUBJECT

      Subject text

      SENT_DATE

      Date in {iso-date-format-link} format e.g. 1970-01-01T00:00:00.000Z

      RECEIVED_DATE

      Date in {iso-date-format-link} format e.g. 1970-01-01T00:00:00.000Z

      FROM

      Address - one or several comma-separated email addresses e.g. Billie Jean <bjean@gmail.com>, Big Boss <boss@company.com>

      CC_RECIPIENTS

      Address - one or several comma-separated email addresses e.g. Billie Jean <bjean@gmail.com>, Big Boss <boss@company.com>

      BCC_RECIPIENTS

      Address - one or several comma-separated email addresses e.g. Billie Jean <bjean@gmail.com>, Big Boss <boss@company.com>

      TO_RECIPIENTS

      Address - one or several comma-separated email addresses e.g. Billie Jean <bjean@gmail.com>, Big Boss <boss@company.com>

      REPLY_TO

      Address - one or several comma-separated email addresses e.g. Billie Jean <bjean@gmail.com>, Big Boss <boss@company.com>

    • rule

  • $scopes - The comma-separated set of the variables scopes.

  • $variableName - The name to prefix text content references.

Example 3. Fetch email message and validate its content
When I fetch email message from `gmail` server filtered by
|parameter     |rule            |value                                       |
|SUBJECT       |EQUAL_TO        |Registration code                           |
|SENT_DATE     |GREATER_THAN    |1970-01-01T00:00:00.000Z                    |
|RECEIVED_DATE |LESS_THAN       |2020-06-14T11:47:11.521Z                    |
|FROM          |IS_EQUAL_TO     |service <regservice@company.com>            |
|CC_RECIPIENTS |CONTAINS        |admin                                       |
|BCC_RECIPIENTS|DOES_NOT_CONTAIN|gmail.com                                   |
|TO_RECIPIENTS |EQUAL_TO        |me <me@company.com>, boss <boss@company.com>|
|REPLY_TO      |MATCHES         |(?i)[0-9]@.*                                |
 and save message content to SCENARIO variable `textContent`
Then `${textContent[1]}` matches `.*Registration code.*`