Final README.md (with Gemfile & Bundler Instructions)

gmail_sms_notifier

A lightweight Ruby tool that monitors your Gmail account and sends an SMS via OpenPhone when new unread emails arrive from specific sender domains (e.g., state.gov, ssa.gov). Ideal for time-critical alerts that should reach your phone — and your wrist via Apple Watch — without unnecessary noise.

Features

• Connects to Gmail using a Google Workspace service account
• Filters by sender domains (e.g., state.gov, ssa.gov)
• Sends SMS alerts using the OpenPhone API
• Designed for crontab use — runs silently in the background
• Marks processed messages as read to avoid duplicate alerts
• Reads config from a YAML file (.config.yml)

Requirements

• Ruby 3.x
• Bundler
• OpenPhone API access
• Gmail API enabled in Google Cloud
• A Google Workspace service account with domain-wide delegation

Installation

1. Clone this repo (or place it in /opt/gmail_sms_notifier)

2. Install dependencies using Bundler:

cd /opt/gmail_sms_notifier
bundle install

This requires a Gemfile in the same directory (included below).

3. Create log directory:

mkdir -p ./log

4. Verify .config.yml exists at /etc/rails-env/.config.yml

.config.yml Format

OPENPHONE_API: "your_openphone_api_key"
OPENPHONE_PHONE_NUMBER_ALERTS: "+15550001111"
OPENPHONE_PHONE_NUMBER: "+15550002222"

GMAIL_CREDENTIALS_PATH: "/etc/rails-env/gmail-credentials.json"
GMAIL_SENDER_KEYWORDS: "state.gov,ssa.gov"
GMAIL_ADDRESS: "your_gmail_address_here"

Gemfile

source 'https://rubygems.org'

gem 'httparty'
gem 'googleauth'
gem 'google-apis-gmail_v1'

Run It Manually

bundle exec ruby main.rb

Cron Job Example

Create a wrapper script at /usr/local/bin/gmail_sms_check.sh:

#!/bin/bash
cd /opt/gmail_sms_notifier
/usr/bin/env bundle exec ruby main.rb >> ./log/gmail_sms_notifier.log 2>&1

Make it executable:

chmod +x /usr/local/bin/gmail_sms_check.sh

Then add this to crontab:

*/15 * * * * /usr/local/bin/gmail_sms_check.sh

Gmail API Access Notes

• Enable the Gmail API in Google Cloud Console

• Set up a service account with domain-wide delegation

• Authorize the following scope in your Workspace Admin Console:

  https://www.googleapis.com/auth/gmail.readonly
  

License

MIT

GitHub

I have been using FairEmail for a couple of years. Email goes to my desk, and to my Android phone using IMAP and 'leave messages on server'. Less than 10 dollars for the pro version. Most importantly, no advertising or data capture.

Thanks for sharing your experience with FairEmail. It's a solid choice for many users, especially with its privacy-focused features and IMAP support.

However, I have plenty of email clients already. The key difference here is that gmail_sms_notifier isn't about email app notifications—it's about sending actual SMS messages via the OpenPhone API when only critical email arrive. This ensures immediate alerts that reach my phone and wrist, even when I'm away from my devices.

Passport Tracking: SMS Notification from state.gov

Screenshot 2025-05-11 at 7.06.56 AM820×346 39.8 KB

I developed this tool specifically to track critical tasks, and it works exactly as I designed it to, including delivering alerts to my Apple Watch.

You can check it out here:

Hey @jgt,

I’m a bit lost by your reply. IMAP is ancient tech — that setup’s been around forever. Email is noisy, spammy, and I avoid it like the plague.

Here’s how I handle alerts instead:

• I get SMS alerts when server load or disk usage crosses a threshold — no email involved.
• I get SMS alerts if a Docker container, Apache, or SSH service goes down.

Screenshot 2025-05-11 at 2.30.41 PM758×118 18.3 KB

• I get SMS alerts from my broker when trades execute or cancel.
• I get SMS alerts when a community post in held in the queue for review.

Screenshot 2025-05-11 at 2.34.00 PM724×158 10.7 KB

• I get SMS alerts if a critical email arrives (like from the US government about my passport) — skipping spam filters and convoluted mail rules.

All of this runs through the OpenPhone API. I hardly use email, and definitely not IMAP — that’s rusted-out tech from 20+ years ago, not something I’d touch in 2025.

I also built a custom app that logs all incoming SMS alerts into a MySQL DB via webhook. A Rails frontend with DataTables lets me sort, search, and filter when needed.

Hope that clears it up. I avoid email for critical alerts unless absolutely forced — and even then, I immediately forward high-priority messages to my phone via SMS. IMAP has been out of my stack for decades.

The only reason I wrote this code is because the US government still sends critical notices via (antique) email — and since I rarely check email, this ensures I get an immediate SMS alert if something important like “your passport has arrived at the embassy” hits my inbox.

I just used a basic webhook and a bash script to catch the incoming POST and parse the JSON with jq. It then sends an email using mailx with the SMS content.

I don't see how this applies to my earlier post.

In my post, I discussing a webhook into gmail which sends an SMS notification.

Maybe it is a language thing, but the post above by @Sikuoshi seems to discuss something quite different and unrelated to coverting gmail messages to SMS messages received as a notice on a mobile phone.