0.0.2 • Public • Published


Easily access your gmail account via node.

Uses oauth 2.0 to auth.


  1. Install npm: curl | sh
  2. Grab this module from npm: npm install gmail-imap
  3. Include it in your program:
  • Coffeescript: Gmail = require 'gmail-imap'
  • Javascript: Gmail = require('gmail-imap');
  1. Create a project to retrieve a Client ID and Client Secret here:
  2. Create a configuration object to pass in:
var cfg = {
    CLIENT_ID: 'Your_client_id_here',
    CLIENT_SECRET: 'Your_client_secret_here'
  1. create a new instance of the gmail client:
  • Coffeescript: gmail = new Gmail cfg
  • Javascript: gmail = new Gmail(cfg);


  1. Get an Auth Url from google (requires clientId and clientSecret): var authUrl = gmail.getAuthUrl();
  2. Redirect the user to the Auth URL: res.redirect(authUrl) (if using Express)
  3. Get an access (and refresh) token from Google: gmail.getAccessToken(code, function(callback) {});
  4. If callback.access_token exists, get the user's e-mail: gmail.getEmail(callback.access_token, function(data) {});
  5. Create an xoauth2 token to pass to gmail: var xoauth2 = gmail.getXOauth2(, callback.access_token);
  6. Now you have an xoauth2 token that you can pass to a library such as MailListener2.


var Gmail = require('gmail-imap');

var cfg = {
    CLIENT_ID: 'Your_client_id_here',
    CLIENT_SECRET: 'Your_client_secret_here'

var gmail = new Gmail(cfg);

// Get gmail's authentication URL
var authUrl = gmail.getAuthUrl();

// redirect user to authUrl

gmail.getAccessToken(code, function(callback) {
  if(callback.access_token) {
    gmail.getEmail(callback.access_token, function(data) {


Gmail (constructor)s - Create a Gmail object

  • Input: cfg (object)
  • Output: none
  • Example: var gmail = new Gmail({clientId: '1234', clientSecret: '5678'});

getAuthUrl - Get the authorization URL from google to redirect the user to authenticate

  • Input: none
  • Output: url (string)
  • Example: var authUrl = gmail.getAuthUrl();

getAccessToken - OAUTH2: Retrieves an access_token and refresh_token.

  • Input: code (from getauthUrl)
  • Output: json { access_token: 'aaaaa', refresh_token: 'bbbbb'}
  • Example: gmail.getAccessToken(code, function(callback) {});

getEmail - Get the user's e-mail address and profile information (Requires Access Token) Note: call this after getAccessToken!

  • Input: access_token
  • Output: json { 'uid': '124', emails: [ value: '' ]}
  • Example: gmail.getEmail(access_token, function(callback) {});

getXOauth2 - Authenticate w/ Gmail's IMAP server (Requires Access Token/Email) Note: call this after getEmail!

  • Input: email, access_token
  • Output: json email object
  • Example: gmail.getXOauth2(email, access_token, function(data) {});

Help, I need an adult!

First step: Check out the /examples folder. It's decently documented.

If you're still having issues, you can submit them here:


v0.0.1 - First release! Woohoo!!

  • Added support for an OAuth2 round trip via access_token and refresh_token
  • Added support for generating an xoauth2 token
  • Started this ugly manual



Package Sidebar


npm i gmail-imap

Weekly Downloads






Last publish


  • bdickason