juttle-gmail-adapter

Juttle Gmail Adapter

Gmail adapter for juttle

This uses the nodejs API for google to read gmail messages. It also uses Batchelor to perform batched email fetches, something that the main google API does not currently support.

Installation / Setup

Check out this repository and the juttle repository into a working directory.

Run npm link in each.

Make sure the following is in your environment:

NODE_PATH=/usr/local/lib/node_modules

Configuration

Configuration involves these steps:

1. Create application credentials that allow your code to access the google nodejs APIs.
2. Authorize a user using Oauth2 to use the application to access gmail.
3. Add the appropriate configuration items to .juttle/config.{js,json}

Create application credentials

To create application credentials, follow the nodejs quickstart instructions. This will result in a file on disk titled client_secret.json with this structure:

{
  "installed": {
    "client_id": "--your-client-id--",
    "project_id": "--your-project-id",
    "auth_uri": "https:\/\/accounts.google.com\/o\/oauth2\/auth",
    "token_uri": "https:\/\/accounts.google.com\/o\/oauth2\/token",
    "auth_provider_x509_cert_url": "https:\/\/www.googleapis.com\/oauth2\/v1\/certs",
    "client_secret": "--your-client-secret-id--",
    "redirect_uris": [
      "urn:ietf:wg:oauth:2.0:oob",
      "http:\/\/localhost"
    ]
  }
}

You'll use this file in the next step.

Authorize a user using OAuth2

You need to create an oauth2 token that allows this program to read your email on your behalf.

To do this, run node create_oauth_token.js from the juttle-gmail-adapter directory.

This will provide a json config block to add to your .juttle/config.{js,json} file.

This will also use the gmail nodejs api to read the list of labels assocated with the authenticated user, to verify that the token was created successfully.

Add the appropriate configuration items to .juttle/config.{js,json}

create_oauth_token.js printed a configuration block like this:

{
  "adapters": {
    "juttle-gmail-adapter": {
      "client-credentials": {
        "installed": {
          "client_id": "--your-client-id--",
          "project_id": "--your-project-id",
          "auth_uri": "https:\/\/accounts.google.com\/o\/oauth2\/auth",
          "token_uri": "https:\/\/accounts.google.com\/o\/oauth2\/token",
          "auth_provider_x509_cert_url": "https:\/\/www.googleapis.com\/oauth2\/v1\/certs",
          "client_secret": "--your-client-secret-id--",
          "redirect_uris": [
            "urn:ietf:wg:oauth:2.0:oob",
            "http:\/\/localhost"
          ]
        }
      },
      "oauth2-token": {
        "access_token": "---your-access-token---",
        "token_type": "Bearer",
        "refresh_token": "---your-refresh-token---",
        "expiry_date": DDDDDDDDDDDDD
      }
    }
  }
}

Add this configuration to your .juttle/config.{js,json} file. If you have an existing "adapters" section, for example:

{
  "adapters": {
    "juttle-twitter-adapter": {...}
  }
}

Add the juttle-gmail-adapter section as a peer item below "adapters":

{
  "adapters": {
    "juttle-twitter-adapter": {...},
    "juttle-gmail-adapter": {...}
  }
}

Usage

I've only used this for historical reads so far. -from and -to are honored. Currently the entire search expression is passed directly through to gmail as the advanced search expression.

Changelog

0.1.0

Released 2015-12-19

Major Changes

• Initial version.

Minor Changes