Email Plugin

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

Installation

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

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 email.imap. prefix must be replaced with email.server.<server-key>. e.g. email.imap.timeout will become email.server.<server-key>.timeout. The <server-key> is a logical name defining single server configuration and referred in steps.

See Configuration example

Steps

Fetch message from an email server

Info

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]

Wording

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

Parameters

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

  2. $filters - Message filters

  3. $scopes - Variable Scopes

  4. $variableName - name to prefix text content references

Usage

Example 2. Sample.story
Scenario: Fetch email message
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.*`

Appendix

Message filters

parameter

Name Description

SUBJECT

Subject text

SENT_DATE

Date in ISO 8061 format

RECEIVED_DATE

Date in ISO 8061 format

FROM

Address

CC_RECIPIENTS

Address

BCC_RECIPIENTS

Address

TO_RECIPIENTS

Address

REPLY_TO

Address

rule

ISO 8061

Date argument must be presented in ISO-8601 format e.g. 1970-01-01T00:00:00.000Z

Address

Address argument is a comma-separated text that holds one or more email addresses e.g. Billie Jean <bjean@gmail.com>, Big Boss <boss@company.com>

Configuration example

Example 3. 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