rvrmail

E-Mails through dataflows

To facilitate sending and receiving of e-mails in dataflows rvrmail is introduced as an adapter. Under the hood rvrmail wraps smtplib and imaplib pythons standard SMTP and IMAP clients.

Getting Started

Run the following command to confirm rvrmail is installed and works:

rvrmail -h

This should provide help listing the available commands for rvrmail.

Each command has its own options and help. To see the details for a given command run:

rvrmail <command> -h

The most used feature is sending e-mails. Run rvrmail send -h to see all of the options available for this.

rvrmail config file

A config yaml file with email service providers SMTP server(for sending) and IMAP server(for receiving) details is required.

config file location

rvrmail looks for default config file which is rvrmail_config.yml.

The following locations are searched in sequence for the config file and the first match is used:

1. If ROVER_CONFIG_DIR environment variable is set, this directory will be checked first.
2. Check ‘./’ local directory
3. Check ‘./.config’ directory
4. Check ‘data/engine/.config’ directory (used for rover installs)

Note that for rovers, the current directory is always /home/rover.

Example config file

Below is an example file with Gmail SMTP and IMAP server config:

smtp:
    defaults:
        profile: gmail_ssl
    profiles:
        gmail_ssl:
            host: smtp.gmail.com
            port: 465
            encryption: SSL
            auth_type: userpass
        gmail_tls:
            host: smtp.gmail.com
            port: 587
            encryption: TLS
            auth_type: userpass
imap:
    defaults:
        profile: gmail_ssl
    profiles:
        gmail_ssl:
            host: imap.gmail.com
            port: 993
            encryption: SSL
            auth_type: userpass

Username and Passwords

Username and Password can either be provided in the config file or RVRMAIL_USERNAME and RVRMAIL_PASSWORD environment variables can be set.

rvrmail Adapter Actions

List Action

List of mailboxes available.

Example dataflow:

name: FetchEmailList
notes: Fetch list of mailboxes available
steps:
  - name: FetchEmailList
    action: rvrmail.list
    params:
        username: username  # Could be set in rvrmail_config.yml RVRMAIL_USERNAME env var
        password: password  # Could be set in rvrmail_config.yml or RVRMAIL_PASSWORD env var

Select Action

To check the message count of a particular mailbox.

Example dataflow:

name: SelectEmailMailbox
notes: Select a mailbox
steps:
  - name: SelectEmailMailbox
    action: rvrmail.select
    params:
        username: username
        password: password
        mailbox: "[Gmail]/All Mail"

For list of accepted parameters for select action, run command:

rvrmail select -h

Search Action

Searching a mailbox will retrieve the headers of messages - see rvrmail search -h for list of accepted parameters.

Example dataflow searching for a subject from a sender:

name: SearchEmailMailbox
notes: Search for email in mailbox
steps:
  - name: SearchEmailMailbox
    action: rvrmail.search
    params:
        mailbox: "[Gmail]/All Mail"
        from: Google
        subject: Critical

Fetch Action

Messages can be downloaded using fetch - see rvrmail fetch -h for list of options and parameters accepted.

Example dataflow fetching unread messages in stealth mode:

name: FetchUnReadEmailStealthMode
notes: Fetch unread e-mails from mailbox in stealth mode
steps:
  - name: FetchUnReadEmailStealthMode
    action: rvrmail.fetch
    params:
        mailbox: "Inbox"
        search_criteria: "UNSEEN"
        stealth_mode: True

Send E-mails

Example dataflow showing sending e-mails by setting subject, body values directly:

name: SendEmailUsingFieldsExample
notes: Send e-mail using individual header fields
steps:
  - name: SendEmailUsingFields
    action: rvrmail.send
    params:
        to: someone@somewhere.com
        subject: Subject Text Goes here
        body: |
            Using the multi-line format
            Makes for easy typing

The to field accepts multiple recipient e-mails separated by commas.

Send Multiple E-mails with jinja2 template

Example Multiple e-mail dataflow with data loop:

name: SendEmailDataLoopExamples
notes: Send multiple e-mails using jinja2 template
steps:
  - name: SendEmailDataLoop
    action: rvrmail.send
    params:
        template_file: "template_file.tmpl"
        data: {
            "users": [
                {
                    "to": "johndoe@somewhere.com",
                    "name": "John",
                    "content": "body text goes here"
                },
                {
                    "to": "janedoe@somewhere.com",
                    "name": "Jane",
                    "content": "body text goes here"
                }
            ]
        }
        data_key: users
        data_loop: True

Example template file:

To: {{ to }}
Subject: Hello {{ name }}

{{ content }}