Getting Started

Requires Java 1.8

First make sure you have java 1.8 installed.

Run the following to check the version:

java -version

If you don't have java installed or if the version is less than 1.8 than please Install Java

Download the .jar file

Next, download the jar file. Go here to get the latest emailscript.jar

Create a directory where you want to do your emailscript and then copy the .jar file there.

Configuration

Emailscript needs to know how to log in to your email server. Emailscript uses yaml files to handle configurations like this. Yaml, if you are unfamiliar with it, is like an improved JSON.

All config files are kept in the config directory. A sample Email Account config file is included in examples/config directory.

Create a config directory inside your emailscript folder. Copy the examples/config/MyEmail.yml file to this directory.

Fill in the appropriate values for your config/MyEmail.yml.

For example, if you have a gmail email account the settings would look something like:

!EmailAccount
nickname: MyEmail
imapHost: imap.gmail.com
user: [email protected]
password: Your password
smtpHost: smtp.gmail.com

Your folder setup should look now like this:

 emailscript
      emailscript.jar
      config
           MyEmail.yml

Running scripts

Your are now ready to run a script. Copy the examples/list.groovy file to your emailscript folder

Make sure you are in your emailscript folder and then run the command:

java -jar emailscript.jar list.groovy  

You should see a listing of the ten most recent emails in your inbox. Something like:

11:18:23.831 INFO  o.emailscript.helpers.ScriptHelper$ - Executing list.groovy with engine groovy
11:18:26.786 INFO  org.emailscript.mail.MailUtils$ - fetching 10 email(s) from Inbox
11:18:27.004 INFO  org.emailscript.mail.MailUtils$ - finishing fetch for Inbox
weeks ago: 0 days ago: 0 from: Spam Report<[email protected]> subject: Subject: Daily report mailbox   [email protected] folder Spam
weeks ago: 0 days ago: 0 from: DailyGood.org<[email protected]> subject: Firsts Are The Antidote To Stuck
weeks ago: 0 days ago: 0 from: Meetup<[email protected]> subject: New Meetup Group:  Lafayette Single Moms Support Network
weeks ago: 0 days ago: 0 from: Susan Fuller [email protected] [phch-main]<[email protected]> subject: [phch-main] Fwd: Your phone co can block the robocalls!
weeks ago: 0 days ago: 0 from: Facebook<[email protected]> subject: Katharina Woodworth updated her status: "My beloved daughter Quena, whom I was..."
weeks ago: 0 days ago: 0 from: SHARON E ENRIGHT<[email protected]> subject: tomorrow night's meal
weeks ago: 0 days ago: 0 from: American Express<[email protected]> subject: We processed your    payment.
weeks ago: 0 days ago: 0 from: Darren Hedges<[email protected]> subject: RE: D'oh!
weeks ago: 0 days ago: 0 from: Patricia McBroom [email protected] [phch-main]<[email protected]> subject: Re: [phch-main] March Wednesday against "Citizens United
weeks ago: 0 days ago: 0 from: Barbara Lynch<[email protected]> subject: PHCH Calendar
11:18:27.094 INFO  org.emailscript.Emailscript$ - finished processing; result: null
11:18:27.122 INFO  org.emailscript.mail.MailUtils$ - closing connections

Congratulations! You have run your first script.

How scripts work

Let's take a look at the actual script:

def emails = MyEmail.foreach(10){ email ->                                                                                                                                                   
    println("from: ${email.from} subject: {email.subject}") 
}

The "MyEmail" variable comes from your config file. You control the name that appears in your script in one of two ways. If there is a "nickname" property, Emailscript uses that. Otherwise Emailscript will use the filename of the .yml file.

If you change the nickname to, say, "Gmail" then your script would then need to look like this:

def emails = Gmail.foreach(10){ email ->                                                                                                                                                   
    println("from: ${email.from} subject: {email.subject}") }

You call foreach() on your EmailAccount. The "10" tells us to grab the 10 most recent emails. Then the closure ({email -> ...}) is run against every email found.

We can add a lot more information if we want. Let's try a variation of this script:

MyEmail.foreach(){
    logger.info("weeks ago: ${email.weeksAgo} days ago: ${email.daysAgo} from: ${email.from} \
        subject: ${email.subject} size: ${Helper.toBytes(email.size)}")}

This script will pull all emails from you inbox. For each mails it logs the following

• weeks old this email is
• days old this email is
• from field
• subject field
• size of message (formatted in KB's, MB's, etc.).

Note there are some injected objects in this script:

• logger - this logs to both a file and the console. The log file is the name of the script ending with ".log". So in this case it's list.log
• Helper - this object has various useful utilities. We are using its "toBytes()" function to nicely format byte values.

More about config

Any yaml file in your config directory is available to any of your scripts. The constructed yaml object gets the name specified by the nickname field (or the file name if there is no nickname field).

The first line in MyMail.yml is !EmailAccount because for some built in types, we create custom objects. In this case it is the EmailAccount object that lets us read and send emails.

For other objects the Yaml parser will simply create a generic object (built using Maps and Lists).

Next steps

I've added a number of useful, working scripts. They demonstrate all the core features of Emailscript.

Go here to start exploring them.