ukko

manage your gmail using google apps script

• ukko
• Using on google drive
• Setting up scheduled execution
• Developing and testing locally
  • Install javascript dependencies
  • Run tests
  • Run lint
  • Run Ukko
  • Extending label rules
  • Contributions

Ukko is a code name for a google apps script runs on google servers. It can get emails in your inbox or use search, looping over email threads and assigning labels based on the email metadata. It's intended be setup via google drive and have time driven trigger.

Using on google drive

1. Access your google drive, click New and select "Google Apps Script".
2. Name the project "Ukko" and paste the contents of modules/ukko.js , exclude import and export statements those are used for testing Ukko locally.
3. Click "Run" icon at the top of the editor, you will be prompted to grant access to your gmail.
4. If there are any messages in your inbox that have header "List-Id" it will create and assign labels.

NOTE:

• Missing labels are created automatically.
• Feel free to delete labels in gmail at any time, they won't be recreated until matching email is processed by Ukko.
• Labels separated by "/" are nested.
• Threads are assigned all labels in the nested chain, for label "lists/my-list/company", following are assigned:
  • "lists"
  • "lists/my-list"
  • "lists/my-list/company"
• Labelled threads are shown at all nesting levels.

NOTE: To automatically "archive" the thread after labels are applied, uncomment following line in modules/ukko.js :

if (labels.length) { inboxThread.moveToArchive() }

Expect similar output when executing the script in google apps script "execution log":

from:[email protected] labels:lists/planet-list
from:[email protected] labels:lists/announce-list
from:nothandled@domain labels:

Setting up scheduled execution

1. Click "Clock" icon named "Triggers".
2. Click "Add Trigger".
3. Make sure "runUkko" is selected along with "Interval" at which Ukko runs.
4. Click save and enjoy!

Developing and testing locally

To try ukko locally you will need nodejs and npm installed on your machine.

Install javascript dependencies

To pull javascirpt dependencies (see package.json) locally run npm install:

[tomas@dev ukko]$ npm install
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: [email protected] (node_modules/fsevents):
npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for [email protected]: wanted {"os":"darwin","arch":"any"} (current: {"os":"linux","arch":"x64"})

added 274 packages from 145 contributors and audited 275 packages in 8.068s

56 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

Run tests

Mocha is used for testing, if you have installed mocha globally you can call it directly with mocha, OR via npm test:

[tomas@dev ukko]$ npm run test

> [email protected] test /ukko
> mocha

from:[email protected] labels:lists/announce-list/example
from:[email protected] labels:lists/planet-list/example


email filter tests
 get regex tests
   ✓ should return email
   ✓ should return jira project
   ✓ should return email
   ✓ should return list id
   ✓ should return to name
 get labels tests
   ✓ should return list of labels for header named List-Id
   ✓ should return list of labels for emails from @github.com
   ✓ should sublabel @github.com when "To" header is set
   ✓ should return list of labels for emails from [email protected]
   ✓ should return list of labels for emails from team
   ✓ should return list of labels for emails from [email protected]
   ✓ should return list of labels for emails for jira
   ✓ should return list of labels for emails for jira project
   ✓ should return list of labels for emails for bugzilla
   ✓ should return list of labels for emails for bugzilla project
   ✓ should return list of labels for emails for bugzilla project acronym and component
   ✓ should not break with empty headers
 should return list of assigned labels
   ✓ output list of processed emails with labels applied
 run filter tests
   ✓ output list of processed emails with labels applied


19 passing (17ms)

Run lint

Eslint is used for linting all js code, if you have installed eslint globally you can call it directly with eslint . OR via npm lint:

[tomas@dev ukko]$ npm run lint

> [email protected] lint /ukko
> eslint .

Run Ukko

To Ukko locally with mock data call node . or npm start

[tomas@dev ukko]$ npm start

> [email protected] start /ukko
> node .

from:[email protected] labels:lists/planet-list
from:[email protected] labels:lists/announce-list

Extending label rules

Modify getLabels function of modules/ukko.js to add your own logic for setting up labels. Few example rules are included with ukko, feel free to change to suit your needs.

Create "catch all" filters for given domain:

// process @github.com
if (messageFrom.includes('@github.com')) {
 labels.push('github')
}

Here's an sample to extract GitLab project name from header named X-GitLab-Project and assign label gitlab/projectname:

// process gitlab notifications
if (message.getHeader('X-GitLab-Project')) {
 labels.push(`gitlab/${message.getHeader('X-GitLab-Project')}`)
}

Here's a sample to assign label from the value of List-Id header, in this example extra label is added where sender domain doesn't match mydomain:

// process mailing lists
if (message.getHeader('List-Id')) {
 // extract my-list from 'My List <my-list.example.com>'
 const listIDshort = getReMatch('listid', message.getHeader('List-Id'))
 let listLabel = 'lists/' + listIDshort
 if (messageFromDomain !== 'mydomain') {
   listLabel += `/${messageFromDomain}`
 }
 labels.push(listLabel)
}

Contributions

• PR are most welcome!
• Please check "issues"
• Read and follow CODE_OF_CONDUCT.md
• Licensed under MIT license
• Clone the repo and raise a pull request
• Love and light