otp-gateway

Zero-dependency Python library for receiving OTP codes via IMAP.

Watch your inbox for verification emails from 30+ platforms — GitHub, Google, Discord, OpenAI, and more. No third-party APIs, no SMS gateways. Just IMAP.

Features

• 🔑 13 OTP extraction patterns — digits, alphanumeric, multi-language
• 📬 IMAP auto-polling with configurable timeout & interval
• 🔗 Verification link extraction from email bodies
• 📛 Alias generation for catch-all domains
• 🔄 Smart dedup — never returns the same OTP twice
• 🐍 Zero dependencies — only Python stdlib
• 🖥️ CLI + Python API — use from terminal or import in code

Install

pip install otp-gateway

Or just copy otp_gateway/ into your project — zero external deps.

Quick Start

Python API

from otp_gateway import OTPGateway, OTPConfig

# Configure
config = OTPConfig(
    imap_email="you@gmail.com",
    imap_password="your-app-password",  # Gmail: use App Password
    domain="yourdomain.com",            # optional: for alias generation
)
gw = OTPGateway(config)

# Option 1: Watch a specific email address
result = gw.wait_for_otp("github-abc123@yourdomain.com")
print(result["value"])  # "847291"

# Option 2: Generate alias + wait
alias = gw.generate_alias("github")
print(alias)  # "github-a7k2m3@yourdomain.com"
# ... use this email to sign up ...
result = gw.wait_for_otp(alias, timeout=90)
print(result["value"])  # the OTP code

# Option 3: One-shot check (no waiting)
result = gw.search_otp("some@email.com")
if result:
    print(result["type"])   # "code", "link", or "raw"
    print(result["value"])  # the OTP code or link

CLI

# Interactive setup
otp-gateway init

# Or pass credentials directly
otp-gateway --email you@gmail.com --password "xxxx" --domain yourdomain.com generate github
otp-gateway --email you@gmail.com --password "xxxx" wait github-a7k2m3@yourdomain.com

# Or use a config file
otp-gateway --config ~/.otp_gateway/config.json generate openai
otp-gateway --config ~/.otp_gateway/config.json check some@email.com
otp-gateway --config ~/.otp_gateway/config.json list

Config

JSON config file (~/.otp_gateway/config.json)

{
  "imap_server": "imap.gmail.com",
  "imap_port": 993,
  "imap_email": "you@gmail.com",
  "imap_password": "your-app-password",
  "domain": "yourdomain.com"
}

Environment variables

export OTP_IMAP_SERVER=imap.gmail.com
export OTP_IMAP_EMAIL=you@gmail.com
export OTP_IMAP_PASSWORD=your-app-password
export OTP_DOMAIN=yourdomain.com

Programmatic

config = OTPConfig(
    imap_server="imap.gmail.com",
    imap_port=993,
    imap_email="you@gmail.com",
    imap_password="your-app-password",
    domain="yourdomain.com",
)

How It Works

1. Catch-all routing: Set up your domain to forward all *@yourdomain.com to one Gmail inbox
2. Alias generation: otp-gateway creates unique aliases like github-a7k2m3@yourdomain.com
3. IMAP polling: When you request an OTP, it polls your inbox for emails sent to that alias
4. Pattern matching: 13 regex patterns extract the OTP code or verification link
5. Dedup: Tracks seen message IDs so the same OTP is never returned twice

Catch-all domain setup

Gmail App Password

1. Go to Google Account → Security → App Passwords
2. Generate a new app password for "Mail"
3. Use that 16-char password as imap_password

Supported Platforms

The library works with any platform that sends OTP via email. Built-in alias prefixes for:

Add custom prefixes:

gw.add_prefix("myplatform", "mp")
alias = gw.generate_alias("myplatform")  # mp-a7k2m3@yourdomain.com

Response Format

{
    "type": "code",           # "code", "link", or "raw"
    "value": "847291",        # the OTP code or link
    "from": "noreply@github.com",
    "subject": "Your GitHub verification code",
    "date": "Mon, 25 Jun 2026 12:00:00 +0000",
    "msg_id": "42"
}

Error Handling

from otp_gateway import OTPGateway, OTPConfig, OTPTimeoutError, IMAPConnectionError

try:
    code = gw.get_otp("test@example.com", timeout=60)
except OTPTimeoutError:
    print("OTP not received in time")
except IMAPConnectionError:
    print("Can't connect to IMAP server")

Tests

pip install pytest
pytest tests/ -v

All tests use mocks — no real IMAP connection needed.

Requirements

• Python 3.10+
• No external dependencies (stdlib only)

License

MIT