A simple Node.js Gmail client which checks/returns email message(s) straight from any Gmail-powered account (both private and company).
There are two main functionalities this library provides:
check_inbox(): Polls a mailbox for a given amount of time. At the end of the operation, the desired message is returned (if found).get_messages(): Can be used to perform various assertions on the email objects (see example below).
P.S, I have written a story on medium, how using Cypress, we are testing our user registration process at Tastewise.
- Install using
npm:
npm install --save-dev gmail-tester
- Save the Google Cloud Platform OAuth2 Authentication file named
credentials.jsoninside an accessible directory (see instructions below). - In terminal, run the following command:
node <node_modules>/gmail-tester/init.js <path-to-credentials.json> <path-to-token.json> <target-email>
<path-to-credentials.json> Is the path to OAuth2 Authentication file.
<path-to-token.json> Is the path to OAuth2 token. If it doesn't exist, the script will create it.
The script will prompt you to go to google.com to activate a token.
Go to the given link, and select the account for <target-email>. Grant permission to view your email messages and settings. At the end of the process you should see the token:
Hit the copy button and paste it to init.js script.
The process should look like this:
-
Follow the instructions to Create a client ID and client secret. Make sure to select
Desktop appfor the application type. -
Once done, go to https://console.cloud.google.com/apis/credentials?project=(project-name)&folder&organizationId and download the OAuth2 credentials file, as shown in the image below. Make sure to replace
(project-name)with your project name.The
credentials.jsonfile should look like this: -
Make sure the Gmail API is activated for your account.
If everything is done right, the last output from the script should be:
[gmail] Found!
Congratulations! gmail-tester is ready to use.
⛔️ Never share or commit credentials.json nor token.json!!! Whoever has it will have full access to your inbox!
credentials: Path to credentials JSON file or JSON Object.
token: Path to OAuth2 token file or JSON Object.
options:
from: String. Filter on the email address of the receiver.to: String. Filter on the email address of the sender.subject: String. Filter on the subject of the email.include_body: boolean. Set totrueto fetch decoded email bodies.include_attachments: boolean. Set totrueto fetch the base64-encoded email attachments.before: Date. Filter messages received before the specified date.after: Date. Filter messages received after the specified date.label: String. The default label is 'INBOX', but can be changed to 'SPAM', 'TRASH' or a custom label. For a full list of built-in labels, see https://developers.google.com/gmail/api/guides/labels?hl=en
Returns:
An array of email objects with the following fields:
[
{
from: "Human Friendly Name <sender@email-address>",
receiver: "your@email-address",
subject: "string",
body: {
html: "string",
text: "string"
}
}
// ...
];Some senders will send you text/html content, the others will send you plain/text, and some will send you both. Make sure you are looking for the content in the right body field.
credentials: Path to credentials JSON file or JSON Object.
token: Path to OAuth2 token file or JSON Object.
options:
from: String. Filter on the email address of the receiver.to: String. Filter on the email address of the sender.subject: String. Filter on the subject of the email.include_body: boolean. Set totrueto fetch decoded email bodies.include_attachments: boolean. Set totrueto fetch the base64-encoded email attachments.before: Date. Filter messages received before the specified date.after: Date. Filter messages received after the specified date.wait_time_sec: Integer. Interval between inbox checks (in seconds). Default: 30 seconds.max_wait_time_sec: Integer. Maximum wait time (in seconds). When reached and the email was not found, the script exits. Default: 60 seconds.label: String. The default label is 'INBOX', but can be changed to 'SPAM', 'TRASH' or a custom label. For a full list of built-in labels, see https://developers.google.com/gmail/api/guides/labels?hl=en
Returns:
An array of email objects with the following fields:
[
{
from: "Human Friendly Name <sender@email-address>",
receiver: "your@email-address",
subject: "string",
body: {
html: "string",
text: "string"
}
}
// ...
];In addition, verbose messages will be written to console.
credentials: Path to credentials JSON file or JSON Object.
token: Path to OAuth2 token file or JSON Object.
Refresh the access token. A new file will overwrite the existing one in token_path.
const path = require("path");
const gmail = require("gmail-tester");
const email = await gmail.check_inbox(
path.resolve(__dirname, "credentials.json"), // Assuming credentials.json is in the current directory.
path.resolve(__dirname, "gmail_token.json"), // Look for gmail_token.json in the current directory (if it doesn't exists, it will be created by the script).
{
subject: "Activate Your Account", // We are looking for 'Activate Your Account' in the subject of the message.
from: "[email protected]", // We are looking for a sender header which is '[email protected]'.
to: "<target-email>", // Which inbox to poll. credentials.json should contain the credentials to it.
wait_time_sec: 10, // Poll interval (in seconds).
max_wait_time_sec: 30, // Maximum poll time (in seconds), after which we'll giveup.
include_body: true
}
);
if (email) {
console.log("Email was found!");
} else {
console.log("Email was not found!");
}const { defineConfig } = require("cypress");
const gmailTester = require("gmail-tester");
const path = require("path");
module.exports = defineConfig({
e2e: {
setupNodeEvents(on, config) {
on("task", {
"gmail:get-messages": async (args) => {
const messages = await gmailTester.get_messages(
path.resolve(__dirname, "credentials.json"),
path.resolve(__dirname, "token.json"),
args.options
);
return messages;
},
});
},
},
});/// <reference types="Cypress" />
describe("Email assertion:", () => {
it("Using gmail_tester.get_messages(), look for an email with specific subject and link in email body", function () {
// debugger; //Uncomment for debugger to work...
cy.task("gmail:get-messages", {
options: {
from: "[email protected]",
subject: "Ubisoft Password Change Request",
include_body: true,
before: new Date(2019, 8, 24, 12, 31, 13), // Before September 24rd, 2019 12:31:13
after: new Date(2019, 7, 23), // After August 23, 2019
},
}).then((emails) => {
assert.isAtLeast(
emails.length,
1,
"Expected to find at least one email, but none were found!"
);
const body = emails[0].body.html;
assert.isTrue(
body.indexOf(
"https://account-uplay.ubi.com/en-GB/action/change-password?genomeid="
) >= 0,
"Found reset link!"
);
});
});
});Please feel free to contribute to this project.
- Built using googleapis.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent