OTP Mailer

Verification Flows

Two independent flows. Choose based on your UX preference — they never mix. A code email never contains a button; a link email never contains a code.

Quick Start

Clone, configure, run — three commands to your first verification email.

1 — Clone and install

git clone https://github.com/pooraddyy/otp-mailer.git
cd otp-mailer
npm install

2 — Configure environment

cp sample.env .env
# Fill in MONGODB_URI, GMAIL_USER, GMAIL_PASS

3 — Run locally

npm run dev
# Listening on http://localhost:5001

Send your first email

# Code flow
curl -X POST http://localhost:5001/api/otp/generate   -H "Content-Type: application/json"   -d '{"email":"you@example.com","organization":"Acme"}'

# Magic link flow
curl -X POST http://localhost:5001/api/otp/send-link   -H "Content-Type: application/json"   -d '{"email":"you@example.com","organization":"Acme"}'

Send OTP Code

Generates a new OTP and sends it to the recipient's inbox as a numeric or alphanumeric code.

{
  "message": "Verification code sent to your email",
  "mode": "code",
  "requestId": "8f0a2c...",
  "validityMinutes": 5
}

Send Magic Link

Sends a one-click "Verify my email" button. Optionally pass a webhookUrl to receive an instant POST callback when the user clicks.

{
  "message": "Verification link sent to your email",
  "mode": "link",
  "requestId": "b7e3...",
  "validityMinutes": 5,
  "webhookRegistered": true
}

Verify by Code

Validates the OTP code the user typed. Single-use — consumed on first success.

{ "email": "user@example.com", "otp": "123456" }

{ "message": "Email verified successfully", "verified": true }

Verify by Link

Browser-facing endpoint embedded in magic link emails. Validates the token, marks the record as verified, and renders a styled confirmation page. You do not call this from your backend — the user's email client does.

Check Status

Returns the verification status of a request. Use this to poll in the magic link flow, or as a fallback if your webhook misses a delivery.

{
  "found": true,
  "verified": false,
  "expired": false,
  "email": "user@example.com"
}

Rate Limiting

Every request to /api/otp/generate and /api/otp/send-link goes through an in-memory rate limiter. Both IP address and email address are tracked independently.

429 Response

{
  "error": "Too many requests. Try again in 12 minutes.",
  "retryAfterSeconds": 720
}

Webhooks

Pass a webhookUrl to POST /api/otp/send-link and the service fires a POST to your server the instant the user clicks the verify button.

Payload delivered to your server

{
  "event": "email.verified",
  "email": "user@example.com",
  "requestId": "b7e3a2f1...",
  "verifiedAt": "2026-05-26T10:30:00.000Z"
}

• Fire-and-forget — the confirmation page does not wait for your server to respond
• 5-second timeout. Slow or unreachable URLs are aborted and logged server-side
• Only http:// and https:// URLs are accepted
• No automatic retries — use GET /api/otp/status/:requestId as a reliable fallback

Environment Variables

All variables live in sample.env. Copy it to .env for local development. For Vercel, add them under Settings → Environment Variables.

Error Reference

All errors return { "error": "message" }.