# isDisposable

> Disposable email detection API and npm package for developers. Block fake signups with one line of code.

## What is isDisposable?

isDisposable is an open-source email trust platform that helps developers detect and block disposable, temporary, and throwaway email addresses. It offers two products:

1. **npm package** (`@isdisposable/js`) — Free, offline detection with 160,000+ known disposable domains. Zero dependencies, synchronous, works anywhere JavaScript runs.

2. **API service** — Real-time detection using DNS/MX analysis, risk scoring (0-100), domain age detection, and pattern matching. Catches brand-new disposable services that aren't in any blocklist.

## Quick Start

### Offline (npm package)
```
npm install @isdisposable/js

import { isDisposable } from '@isdisposable/js';
isDisposable('test@mailinator.com'); // true
isDisposable('user@gmail.com');      // false
```

### Real-time (API client)
```
import { createIsDisposable } from '@isdisposable/js';

const client = createIsDisposable({ apiKey: 'isd_your_key' });
const { disposable, score, reason } = await client.check('test@example.com');
```

### REST API
```
POST https://isdisposable.com/api/v1/check
Header: x-api-key: isd_your_key
Body: { "email": "test@mailinator.com" }

Response: { "disposable": true, "score": 95, "reason": "blocklist_match" }
```

## Key Features

- 160,000+ disposable domains in offline blocklist
- Real-time DNS/MX fingerprinting for unknown domains
- Risk score 0-100 for every email
- Domain age detection via RDAP
- Self-referencing MX detection
- Suspicious IP pattern matching
- Custom blocklist/allowlist per user
- Built-in caching and offline fallback in SDK
- Bulk checking (up to 100 emails per request)
- Privacy by design — only domain is logged, never full email

## API Response Format

```json
{
  "disposable": true,
  "email": "test@mailinator.com",
  "domain": "mailinator.com",
  "score": 95,
  "reason": "blocklist_match",
  "mx_valid": true,
  "domain_age_days": 4380,
  "cached": false
}
```

## Score Calculation

- 95: Domain in blocklist (160k+ domains)
- 40: No valid MX records
- 30: Domain registered < 7 days ago
- 20: MX points to known disposable infrastructure
- 15: Domain registered < 30 days ago
- 5: Clean — valid MX, old domain, not in blocklist
- Score >= 50 is considered disposable

## Pricing

- Free: 100 API checks/month, 5 req/min, 1 API key
- Pro ($9/mo): 10,000 checks/month, 60 req/min, DNS/MX checks, risk scoring, analytics
- Business ($29/mo): 100,000 checks/month, 120 req/min, 5 API keys
- Scale ($79/mo): 500,000 checks/month, 300 req/min, unlimited API keys

The npm package is always free and unlimited for offline usage.

## Integrations

Works with: Next.js, Express, Fastify, Better Auth, Supabase Auth, and any JavaScript/TypeScript framework.

## Links

- Website: https://isdisposable.com
- Docs: https://isdisposable.com/docs
- npm: https://www.npmjs.com/package/@isdisposable/js
- GitHub: https://github.com/isdisposable/js
- API Reference: https://isdisposable.com/docs/api-reference
- Pricing: https://isdisposable.com/pricing