Mailing 📨

Utility to make sending mail easier, particularly with Google Gmail and OAuth2.

Install

npm install @frontboi/mailing

Support

You can create a PR on this project and I will review it. If you prefer, you can contact me on Linkedin or by email (contact@tomblanchet.fr).

Features

This package is meant to facilitate the integration of Google's gmail API and OAuth2 for mailing. As such, it provides functions to generate Google OAuth2 client and access/refresh token to keep so you can use it for mail sending.

• generateOAuthUrl: returns an authentication URL to redirect your client to so that it authorizes OAuth connection.
• validateAuthCode: when a user successfuly authorized OAuth, he gets redirect to GOOGLE_REDIRECT_URI with a code in query params. Provide this code to this function in order to exchange it for access and refresh tokens.
• forgeAccessToken: provide a refresh token to this function, and it will yield you an access token.
• getUserInfos: returns general informations about the connected user.

Setup

Google console

You will need to setup a Google Console project. Go to this url, and then create your application. You must include these three scopes: /auth/userinfo.email, /auth/userinfo.profile and /auth/gmail.send for this package to work.

Environment variables

To use frontboi's mailing utility, these environment variables must be accessible at runtime:

• GOOGLE_OAUTH_CLIENT_ID
• GOOGLE_OAUTH_SECRET
• GOOGLE_REDIRECT_URI

These values are obtained via after you have created you Google Console project.

How to use

Here is an implementation example in an Express server:

import { generateOAuthUrl, validateAuthCode, sendMail, getUserInfos } from '@frontboi/mailing'

import express from 'express'

const app = express()

// 1. redirect the user to the Google OAuth2 page, in order to get a code that will be used in the next step
//    the code will be sent to the GOOGLE_REDIRECT_URI endpoint - you have configured this endpoint in the Google cloud console
app.get('/authenticate', (req, res) => {
  const authUrl = generateOAuthUrl()
  res.redirect(authUrl)
})

// 2. request this endpoint with the code you obtained earlier
app.post('/get-tokens', (req, res) => {
    const { tokens } = await validateAuthCode(req.body.code)
    const { access_token, refresh_token } = tokens
    // do what you want with your tokens (save the refresh token in database for example)
})

// 3. send a mail using the token you obtained
app.get('/send-mail', (req, res) => {
    const refreshToken // get it the way you like

    // get sender's Google profile informations
    const { email, given_name, family_name } = await getUserInfos(refreshToken)

    await sendMail({
      from: email,
      refreshToken,
      attachments: [],
      subject: 'Hello Henry',
      to: 'henri.letesquieux@orange.fr',
      body: `${given_name} ${family_name} managed to send a mail using Gmail !`,
    })
})

app.listen(port, () => console.log(`Server is running on http://localhost:${port}`))