1. Overview
This guide documents how I configured a Linux-based SMTP relay server to allow office copiers to send email securely through Gmail. The project solved the challenge of devices that do not support OAuth2 authentication, enabling them to send authenticated email while complying with Gmail’s security requirements.
This SMTP relay solution:
-
Authenticates outbound email via Gmail using OAuth2
-
Restricts relay access to specific copier subnets
-
Automates token management to avoid manual intervention
The relay acts as a secure bridge between legacy hardware (that can’t support modern authentication) and Gmail’s stricter authentication requirements.
2. Assumptions
This solution was designed under the following assumptions:
-
The organization uses Gmail or Google Workspace as its email provider.
-
Copiers and scanners on the network do not support OAuth2 authentication for SMTP.
-
A dedicated Linux server or virtual machine was available to serve as the SMTP relay, running Ubuntu 22.04 LTS.
-
The copier network is isolated or controlled (e.g., a trusted subnet such as
192.0.2.0/24). -
A Google Cloud project was created with access to OAuth2 credentials (client ID, client secret) and a refresh token.
-
The relay would only send outbound email (no need to receive inbound mail).
-
All outbound email must be authenticated and delivered via Gmail’s SMTP servers.
3. Objectives
The primary goals of this project were:
-
Enable copiers without OAuth2 support to send email through Gmail
-
Create a secure relay server to handle email from trusted copier IPs
-
Authenticate outbound email to Gmail using OAuth2 via
msmtp -
Automate access token handling using a refresh token
-
Restrict relay access to a specific network subnet
-
Provide a maintainable, repeatable process for future devices
4. Technical Setup
This solution was implemented using a combination of Postfix and msmtp on a dedicated Linux virtual machine.
Key components:
| Component | Purpose |
|---|---|
| Postfix | Accepts SMTP traffic from copiers and relays mail |
| msmtp | Sends authenticated email via Gmail using OAuth2 |
| refresh_token.sh | Script to automatically refresh OAuth2 access token |
| Linux VM (Ubuntu) | Hosts the relay server with a static IP address |
5. Google Cloud Project Setup
Since Gmail requires OAuth2 authentication for SMTP access, I needed to create a Google Cloud project to generate OAuth2 credentials and obtain a refresh token for automated authentication.
Steps to set up Google Cloud Project:
-
Logged into Google Cloud Console.
-
Created a new project named
smtp-relay-project. -
Enabled the Gmail API in the project:
-
Navigated to APIs & Services → Library.
-
Searched for “Gmail API” and clicked “Enable”.
-
-
Created OAuth2 credentials:
-
APIs & Services → Credentials → Create Credentials → OAuth Client ID.
-
Application Type: Web Application.
-
Gave it a name like
smtp-relay-client. -
Added
http://localhostto Authorized Redirect URIs.
-
-
Downloaded the client secret JSON file for later use.
6. Generating the Refresh Token
I wrote a Bash script to simplify obtaining the refresh token from Google’s OAuth2 API.
The script generates the authorization URL, prompts the user to paste in the authorization code from Google, and exchanges it for a refresh token.
Here’s the script:
How it works:
-
Outputs an authorization URL.
-
Prompts user to visit the link, log into Google with the account that you want to send the emails from, and paste the returned code.
-
Exchanges the code for a refresh token and prints it.
I ran the script, saved the refresh token output, and used it later in the msmtp configuration.
7. Installing Postfix (Send-Only)
Installed Postfix as a send-only mail transfer agent to accept mail from copiers and hand it off to msmtp for delivery.
During setup:
-
Selected “Internet Site”.
-
Set mail name to
exampledomain.com.
Verified /usr/sbin/sendmail points to Postfix:
Confirmed Postfix installed and ready.
8. Installing msmtp
Installed msmtp to act as the authenticated SMTP client to Gmail:
9. Configuring msmtp
Created configuration file at /usr/local/etc/msmtprc:
This config instructs msmtp to use Gmail SMTP with OAuth2, pulling access tokens from the refresh script.
10. OAuth2 Token Refresh Script
Created /usr/local/bin/refresh_token.sh to automatically fetch a fresh access token using the saved refresh token:
Made the script executable:
Confirmed valid access token output.
11. msmtp Wrapper Script for Postfix
Postfix uses sendmail or a pipe command to send mail, so I created a wrapper to invoke msmtp:
Contents:
Made executable:
12. Configuring Postfix to Use msmtp
Once msmtp and the wrapper script were ready, I integrated it with Postfix and secured the relay so that only authorized copier IPs could send mail through it.
Integrating msmtp into Postfix
Edited /etc/postfix/master.cf to add a custom msmtp transport:
This tells Postfix to hand off messages using the wrapper script we wrote.
Edited /etc/postfix/main.cf to activate the new transport:
Reloaded Postfix:
At this point, mail accepted by Postfix is passed directly to msmtp for authenticated delivery through Gmail.
13. Restricting Access to Copier Subnet
To ensure only authorized copiers could send mail, I updated the Postfix config to allow mail only from a trusted internal subnet.
In /etc/postfix/main.cf, I added:
-
mynetworksdefines allowed source IPs (copier subnet). -
smtpd_recipient_restrictionsblocks all other relaying attempts.
Reloaded Postfix again:
This ensures only devices on the copier subnet are allowed to relay messages.
14. Configuring the Copier to Use the SMTP Relay
Once the relay server was configured and secured, I updated the copier’s SMTP settings so it could send scans through the relay.
Copier SMTP Settings
On the copier’s admin interface, I configured the following:
| Setting | Value |
|---|---|
| SMTP Server | 192.0.2.10 |
| Port | 25 |
| SSL/TLS | Disabled |
| Authentication | None |
| Sender Address | copier@exampledomain.com |
