phone-sms-gateway

phone-sms-gateway — turn your Android phone into a free SMS gateway

A phone SMS gateway in your terminal. Send SMS, generate and verify OTP codes, read your inbox — all routed through your own Android phone instead of paying Twilio, Vonage, MessageBird, or Plivo.

npx phone-sms-gateway send [phone] "Hello from my phone"

The message leaves your real mobile number and arrives in the recipient's regular SMS app. No CPaaS account. No per-SMS fees. No A2P 10DLC paperwork.

Why a phone SMS gateway?

CPaaS providers charge $0.0075 to $0.04 per SMS in the US, force you through A2P 10DLC registration, and route messages from short codes recipients don't recognise. Reply rates collapse.

A phone-based SMS gateway routes through the Android phone you already own. Messages arrive from your real local number. Recipients reply directly to you. And the cost is $29/month flat for unlimited SMS through one device.

This package gives you a CLI for that flow.

Install

# One-off
npx phone-sms-gateway send [phone] "Hi"

# Or install globally
npm install -g phone-sms-gateway
phone-sms-gateway send [phone] "Hi"
# alias also installed:
sms-gateway send [phone] "Hi"

Node 18 or newer.

Quick start

• Sign up free at sms8.io (5-day trial, no card)
• Install the SMS8 Android app on any Android phone, pair it with your account
• Grab your API key from app.sms8.io/api.php
• Set the key once:

  export SMS8_API_KEY=sk_xxx
  

• Send your first SMS:

  phone-sms-gateway send [phone] "It works!"
  

Commands

# SMS
phone-sms-gateway send <phone> "<message>"

# OTP / 2FA
phone-sms-gateway otp send <phone>
phone-sms-gateway otp verify <phone> <code>
phone-sms-gateway otp wait <sender-phone> [--timeout=120]

# Inbox
phone-sms-gateway inbox [--limit=25] [--received] [--sent] [--phone=[phone]]

# Devices
phone-sms-gateway devices

# Account
phone-sms-gateway balance
phone-sms-gateway setup

Device / SIM routing

Pick which paired Android phone (and which SIM on multi-SIM phones) sends each message:

phone-sms-gateway send [phone] "Hi" --device-id=10700 --sim-slot=2
phone-sms-gateway send [phone] "Hi" --devices=10700,10701|0
phone-sms-gateway send [phone] "Broadcast" --option=1     # all devices
phone-sms-gateway send [phone] "Broadcast" --option=2     # all SIMs across all devices
phone-sms-gateway send [phone] "Hi" --random-device       # load-balance

The same flags work on otp send and otp wait. Run phone-sms-gateway devices to list IDs.

OTP send options

phone-sms-gateway otp send [phone] --length=8 --expires-in=180
phone-sms-gateway otp send [phone] --template="Your YourApp code: {code}"

OTP verify

otp verify checks the most-recent unverified code for the phone. No device routing needed (the code lives server-side).

phone-sms-gateway otp verify [phone] 482937

OTP wait

otp wait watches incoming SMS on a paired Android and extracts the verification code. Pass the sender's phone or partial match:

CODE=$(phone-sms-gateway otp wait +Google --contains="Google" --timeout=180)

Example: send notifications from a cron job

# /etc/cron.hourly/server-watchdog
LOAD=$(uptime | awk -F'load average:' '{print $2}')
phone-sms-gateway send [phone] "Server load: $LOAD" --api-key=$SMS8_API_KEY

Example: OTP loop in CI

# Trigger your app's OTP send
curl -X POST https://staging.app.com/otp -d 'phone=[phone]'

# Block until the SMS arrives on the test SIM
CODE=$(phone-sms-gateway otp wait [phone] --timeout=180)

# Hand it back to the app
curl -X POST https://staging.app.com/verify -d "code=$CODE"

What's under the hood

This package shares its codebase with sms8-cli and connects to the SMS8 SMS-gateway platform. Pick whichever package name reads better in your toolchain — they expose the same bin/sms8.js.

For an AI / MCP integration (Claude Code, Cursor, Windsurf), see sms8-mcp.

Links

• Phone SMS gateway home: sms8.io
• Android app: sms8.io/sms-gateway-apk-android
• Dashboard: app.sms8.io
• API docs: sms8.io/sms-api-documentation
• GitHub: github.com/1fancy/sms8-sms-gateway

License

MIT