⚡ @fadsync/mailcheck-edge

The Official Node.js SDK & Express/Next.js Middleware for FadSync MailCheck.
Block 40M+ disposable burner emails, autocorrect domain typos, verify DNS MX records, and protect user signups with sub-50ms latency.

🚀 Features

• 🚫 40M+ Disposable Email Detection: Real-time identification of burner domains (10minutemail, GuerrillaMail, Mailinator, etc.).
• ⚡ Sub-50ms Verification: Built-in in-memory LRU/TTL cache to prevent redundant API queries.
• 🛡️ 1-Line Express & Connect Middleware: Protect signup and authentication routes with zero boilerplate.
• 💡 Smart Typo Autocorrect: Automatically catches and fixes domain typos ([email protected] ➔ [email protected]).
• 🔄 Fail-Silent Resilience (failSilent: true): Network blips or upstream latency will never break user registration.
• 🔑 Direct Authentication: Seamless connection with standard FadSync API keys (Authorization: Bearer <API_KEY>).
• 📘 First-Class TypeScript Support: Full .d.ts type declarations included out of the box.

📦 Installation

npm install @fadsync/mailcheck-edge
# or
yarn add @fadsync/mailcheck-edge
# or
pnpm add @fadsync/mailcheck-edge

🔑 Getting Your API Key

1. Create a free account at https://mailcheck.fadsync.com/.
2. Copy your API Key from the Developer Dashboard.
3. Pass it to MailCheck or set the FADSYNC_API_KEY environment variable.

⚡ Quickstart

1. Direct Node.js Usage

const { MailCheck } = require('@fadsync/mailcheck-edge');

const mailcheck = new MailCheck({
  apiKey: process.env.FADSYNC_API_KEY, // or pass directly 'fsk_live_...'
});

async function run() {
  const result = await mailcheck.verify('[email protected]');

  if (result.isBlocked) {
    console.log(`❌ Blocked: ${result.userFriendlyMessage}`);
    // Output: "Temporary and disposable email addresses are not permitted. Please use a permanent email."
  } else {
    console.log(`✅ Safe to register! Risk score: ${result.riskScore}/100`);
  }
}

run();

2. Express.js / Connect Middleware Guard

Drop into your signup or login route in 1 line:

const express = require('express');
const { mailCheckMiddleware } = require('@fadsync/mailcheck-edge');

const app = express();
app.use(express.json());

// 🛡️ Protect signup route against disposable emails & dead MX records
app.post('/api/signup', mailCheckMiddleware({
  apiKey: process.env.FADSYNC_API_KEY,
  blockDisposable: true, // Blocks 40M+ burner domains
  autoFixTypo: true,     // Autocorrects '[email protected]' to '[email protected]'
}), async (req, res) => {
  const { email, name, password } = req.body;

  // Access validation metadata directly from req.mailCheck
  console.log(`Verified email for ${name}: ${email} (Risk: ${req.mailCheck.riskScore}/100)`);

  // Persist safe user to database (PostgreSQL, MongoDB, Prisma, etc.)
  return res.status(201).json({
    success: true,
    message: 'User registered successfully!',
    user: { name, email },
  });
});

app.listen(3000, () => console.log('Server running on http://localhost:3000'));

When a temporary email is posted, the middleware automatically returns HTTP 422 Unprocessable Entity:

{
  "success": false,
  "error": "Temporary and disposable email addresses are not permitted. Please use a permanent email.",
  "code": "DISPOSABLE_EMAIL_BLOCKED",
  "suggestedEmail": null,
  "details": {
    "email": "[email protected]",
    "isDisposable": true,
    "riskScore": 95,
    "hasValidMx": true
  }
}

3. Next.js API Routes (App Router & Pages Router)

// app/api/auth/signup/route.ts
import { NextResponse } from 'next/server';
import { MailCheck } from '@fadsync/mailcheck-edge';

const mailcheck = new MailCheck({
  apiKey: process.env.FADSYNC_API_KEY,
});

export async function POST(req: Request) {
  const { email, password } = await req.json();

  const check = await mailcheck.verify(email);

  if (!check.isSafeToRegister) {
    return NextResponse.json(
      { error: check.userFriendlyMessage },
      { status: 400 }
    );
  }

  // Safe to save user in database
  return NextResponse.json({ success: true, email: check.email });
}

⚙️ Configuration Options

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | apiKey | string | process.env.FADSYNC_API_KEY | Your FadSync API Key | | baseUrl | string | https://mailcheck.fadsync.com/api/v1 | API base endpoint | | timeout | number | 3000 | Request timeout in milliseconds | | cache | boolean \| object| true (5m TTL) | In-memory cache configuration | | failSilent | boolean | true | Fail-open gracefully on timeouts / API blips |

📊 Result Object Properties

| Property | Type | Description | | :--- | :--- | :--- | | result.email | string | Normalized email address | | result.isDisposable | boolean | true if domain is temporary burner | | result.isValidFormat | boolean | true if RFC format is valid | | result.hasValidMx | boolean | true if DNS MX mail server records exist | | result.riskScore | number | Fraud risk rating from 0 (clean) to 100 (high risk) | | result.typoFix | string \| null | Suggested domain autocorrection | | result.hasTypoSuggestion | boolean | true if typo fix is available | | result.isSafeToRegister | boolean | Convenient boolean check for signups | | result.userFriendlyMessage | string | Localized error explanation for UI/API |

📄 License

MIT © FadSync