ms-oauth-imap

ms-oauth-imap is a Node.js package that integrates Microsoft OAuth authentication with IMAP email access. It provides functions to generate an OAuth URL, retrieve access tokens, refresh tokens, list available mailbox folders, and read emails from specified folders.

Features

• Generate an OAuth authentication URL
• Retrieve an access token using an authorization code
• Refresh expired tokens
• List available mailbox folders (Inbox, Sent, Drafts, etc.)
• Read emails from specified mailboxes

Installation

Run the following command to install the package:

1npm install ms-oauth-imap

Prerequisites

• A Microsoft account with access to Outlook email.
• A registered application on the Azure Portal to obtain your clientId and clientSecret.
• A configured redirect URI for your application.

Usage

1. Import the Package

1const {
2  generateAuthUrl,
3  getToken,
4  refreshToken,
5  readMail,
6  listFolders,
7} = require("ms-oauth-imap");

2. Generate the OAuth URL

1const authUrl = generateAuthUrl({
2  clientId: "YOUR_CLIENT_ID",
3  clientSecret: "YOUR_CLIENT_SECRET",
4  redirectUri: "http://localhost:4000/auth/callback",
5  scope:
6    "openid offline_access https://outlook.office.com/IMAP.AccessAsUser.All",
7  state: "optional-state",
8});

3. Retrieve the Access Token

1const token = await getToken({
2  clientId: "YOUR_CLIENT_ID",
3  clientSecret: "YOUR_CLIENT_SECRET",
4  redirectUri: "http://localhost:4000/auth/callback",
5  code: "AUTHORIZATION_CODE_FROM_QUERY",
6  scope:
7    "openid offline_access https://outlook.office.com/IMAP.AccessAsUser.All",
8});

4. Refresh the Token

1const refreshedToken = await refreshToken({
2  clientId: "YOUR_CLIENT_ID",
3  clientSecret: "YOUR_CLIENT_SECRET",
4  refreshToken: token.refresh_token,
5});

5. List Available Mailbox Folders

1const folders = await listFolders({
2  userEmail: "YOUR_EMAIL_ADDRESS",
3  accessToken: token.access_token,
4});

6. Read Emails from a Folder

1const emails = await readMail({
2  userEmail: "YOUR_EMAIL_ADDRESS",
3  accessToken: token.access_token,
4  folder: "INBOX", // Can be 'INBOX', 'Sent Items', 'Drafts', etc.
5});

Sample Integration with Express

1const express = require("express");
2const session = require("express-session");
3const { simpleParser } = require("mailparser");
4const util = require("util");
5const {
6  generateAuthUrl,
7  getToken,
8  refreshToken,
9  readMail,
10  listFolders,
11} = require("ms-oauth-imap");
12const app = express();
13
14app.use(session({ secret: "secret", resave: false, saveUninitialized: true }));
15
16app.get("/auth", (req, res) => {
17  const url = generateAuthUrl({
18    clientId: "YOUR_CLIENT_ID",
19    clientSecret: "YOUR_CLIENT_SECRET",
20    redirectUri: "http://localhost:4000/auth/callback",
21    scope:
22      "openid offline_access https://outlook.office.com/IMAP.AccessAsUser.All",
23  });
24  res.redirect(url);
25});
26
27app.get("/auth/callback", async (req, res) => {
28  const code = req.query.code;
29  try {
30    const token = await getToken({
31      clientId: "YOUR_CLIENT_ID",
32      clientSecret: "YOUR_CLIENT_SECRET",
33      redirectUri: "http://localhost:4000/auth/callback",
34      code,
35      scope:
36        "openid offline_access https://outlook.office.com/IMAP.AccessAsUser.All",
37    });
38    req.session.token = token;
39    res.send("Authentication successful");
40  } catch (error) {
41    res.status(500).send(error.message);
42  }
43});
44
45app.get("/refresh-token", async (req, res) => {
46  if (!req.session.token) {
47    return res.status(401).send("User not authenticated");
48  }
49  try {
50    const newToken = await refreshToken({
51      clientId: "YOUR_CLIENT_ID",
52      clientSecret: "YOUR_CLIENT_SECRET",
53      refreshToken: req.session.token.refresh_token,
54    });
55    req.session.token = newToken;
56    res.send("Token refreshed successfully");
57  } catch (error) {
58    res.status(500).send(error.message);
59  }
60});
61
62app.get("/list-folders", async (req, res) => {
63  if (!req.session.token) {
64    return res.status(401).send("User not authenticated");
65  }
66
67  try {
68    const folders = await listFolders({
69      userEmail: "YOUR_EMAIL_ADDRESS",
70      accessToken: req.session.token.access_token,
71    });
72    res.send(`<pre>${util.inspect(folders, { depth: null })}</pre>`);
73  } catch (error) {
74    res.status(500).send(error.message);
75  }
76});
77
78app.get("/read-mail", async (req, res) => {
79  if (!req.session.token) {
80    return res.status(401).send("User not authenticated");
81  }
82
83  try {
84    let accessToken = req.session.token.access_token;
85
86    const expiresAt = req.session.token.expires_at || 0;
87    if (Date.now() >= expiresAt) {
88      try {
89        const newToken = await refreshToken({
90          clientId: "YOUR_CLIENT_ID",
91          clientSecret: "YOUR_CLIENT_SECRET",
92          refreshToken: req.session.token.refresh_token,
93        });
94        req.session.token = {
95          ...newToken,
96          expires_at: Date.now() + newToken.expires_in * 1000,
97        };
98        accessToken = newToken.access_token;
99      } catch (refreshError) {
100        return res
101          .status(401)
102          .send('Session expired. Please <a href="/auth">re-authenticate</a>.');
103      }
104    }
105
106    const mails = await readMail({
107      userEmail: "YOUR_EMAIL",
108      accessToken,
109      folder: "INBOX",
110    });
111
112    if (!mails || mails.length === 0) {
113      return res.status(404).send("No emails found.");
114    }
115
116    let html =
117      "<html><head><meta charset='utf-8'><title>Emails</title></head><body>";
118
119    await Promise.all(
120      mails.map(async (mail, index) => {
121        if (!mail.header || !mail.body) {
122          return { error: "Incomplete email data" };
123        }
124
125        try {
126          const emailContent = `${mail.header}\r\n${mail.body}`;
127          const parsed = await simpleParser(emailContent);
128
129          html += `<h2>Email #${index + 1}</h2>`;
130          html += `<h3>From:</h3> ${parsed.from?.text || "Unknown Sender"}`;
131          html += `<h3>To:</h3> ${parsed.to?.text || "Unknown Recipient"}`;
132          html += `<h3>Subject:</h3> ${parsed.subject || "No Subject"}`;
133          html += `<h3>Date:</h3> ${parsed.date || "Unknown Date"}`;
134          html += `<h3>Body:</h3>${parsed.html || parsed.text || "No Content"}`;
135          html += `<hr>`;
136
137          return parsed;
138        } catch (parseError) {
139          return { error: "Failed to parse email content" };
140        }
141      })
142    );
143
144    html += "</body></html>";
145    res.send(html);
146  } catch (error) {
147    res.status(500).send(error.message);
148  }
149});
150
151app.listen(4000, () => {
152  console.log("Server running on port 4000");
153});

Error Handling

This package validates required parameters and throws descriptive errors if any parameter is missing or invalid.

License

MIT License

Contributing

Contributions are welcome. Open an issue or submit a pull request to improve the package.