Implementing Gmail Sending with Cloudflare Workers - Setup Guide

This is Part 1 of a series on implementing Gmail sending with Cloudflare Workers:

• Part 1: Setup (Current)
• Part 2: Development Environment (Coming Soon)
• Part 3: Implementation (Coming Soon)

Introduction

When implementing contact forms on static websites hosted on Cloudflare Pages, email sending functionality requires a serverless solution. This guide demonstrates how to set up Gmail API with Cloudflare Workers for handling form submissions.

Cloudflare Workers Constraints

When working with Cloudflare Workers, there are two major limitations to consider:

1. Google API Package Unavailable:

   • Cloudflare Workers is not a Node.js environment
   • Direct HTTP requests to Google API REST endpoints must be used instead of Node.js client libraries

2. Nodemailer Package Unavailable:

   • Nodemailer depends on Node.js environment
   • Cannot be used in Cloudflare Workers

Setup Process

1. Create a Service Account

1. Access Google Cloud Console
2. Create a new project or select an existing one
3. Navigate to "IAM & Admin" > "Service Accounts"
4. Click "Create Service Account"
5. Enter service account name and description
6. Skip optional settings and click "Done"
7. Note the OAuth2 Client ID for later use

2. Assign Required Roles

1. Navigate to "IAM & Admin" > "IAM"
2. Select the relevant principal
3. Click "Grant Access"
4. Add the service account as a new principal
5. Assign the following roles:
   • Service Account Admin
   • Service Account Key Admin
   • Service Account Token Creator
   • IAP Policy Admin
6. Save the changes

3. Enable Gmail API

1. Navigate to "APIs & Services" > "Library"
2. Search for "gmail"
3. Select "Gmail API"
4. Click "Enable"

4. Add Organization Policy Admin Role

1. Navigate to "IAM & Admin" > "IAM"
2. Edit the organization admin
3. Add "Organization Policy Admin" role
4. Save changes

5. Disable Service Account Key Creation Policy

1. Navigate to "IAM & Admin" > "Organization Policies"
2. Filter for "iam.disableServiceAccountKeyCreation"
3. Click the policy link
4. Click "Manage Policy"
5. Select "Override parent policy"
6. Add rule and set to "Enforced"
7. Click "Done"

6. Generate Service Account Key

1. Navigate to "IAM & Admin" > "Service Accounts"
2. Select the created service account
3. Go to "Keys" tab
4. Click "Add Key" > "Create New Key"
5. Select JSON format
6. Create and securely store the downloaded JSON file

7. Configure Domain-Wide Delegation

1. Access Google Workspace Admin Console
2. Navigate to Security > Access and Data Control > API Controls
3. Click "Manage Domain Wide Delegation"
4. Add new client ID:
   • Enter the service account's client ID
   • Add scope: https://www.googleapis.com/auth/gmail.send
5. Click "Authorize"

Note: Domain-wide delegation should be carefully considered in larger organizations due to security implications.

Additional Configuration

When sending emails from Gmail aliases, remember to add the alias address:

1. Go to Gmail Settings > Accounts
2. Add the alias email address through "Add another email address"

Important Note About Free Email Services

Previously, MailChannels Send API was widely recommended as a free email sending solution for Cloudflare Workers. However, as of June 30, 2024, the integration between MailChannels and Cloudflare has been discontinued. This has affected many developers who relied on this service for their email sending needs.

Many AI language models still suggest MailChannels as a solution because their training data predates this service discontinuation. This situation highlights the importance of verifying current service availability, especially when working with third-party integrations.

The Gmail API implementation described in this guide serves as a reliable alternative, though it requires more initial setup compared to the previous MailChannels solution.

Next Steps

The next article in this series will cover the development environment setup and implementation details for using the Gmail API with Cloudflare Workers.