# Syvel

> Syvel is a Made-in-France REST API for detecting disposable, temporary, and risky email addresses. It helps SaaS companies, e-commerce platforms, and developers protect sign-up forms, reduce fraud, and maintain clean, deliverable user bases — while staying 100% GDPR-compliant.

## About Syvel

Syvel provides a simple REST API (`GET /v1/check/{email}`) that analyzes any email address or domain in real time and returns a structured risk assessment in under 50 ms.

Key facts:
- Hosted in France (EU), GDPR-compliant by design — no personal data retained after the request
- Detects 100,000+ disposable/throwaway email domains, updated daily via live DNS fingerprinting
- Returns structured JSON with: risk score (0–100), deliverability score, reason, MX provider label, typo suggestion, alias detection
- Local part analysis: detects role accounts (contact@, admin@, info@…), random strings, and suspicious patterns
- Authentication: Bearer token — `Authorization: Bearer sv_live_xxxxx`
- Plans: Free (100 req/month) · Starter (1,000/month) · Pro (10,000/month) · Business (100,000/month)
- Pricing: https://syvel.io/pricing
- Dashboard: https://app.syvel.io
- Sign up (free): https://app.syvel.io/register

## Quick Example

```
GET https://api.syvel.io/v1/check/user@yopmail.com
Authorization: Bearer sv_live_xxxxx
```

```json
{
  "email": "a9****e5@yopmail.com",
  "is_risky": true,
  "risk_score": 100,
  "reason": "disposable",
  "is_free_provider": false,
  "is_corporate_email": false,
  "did_you_mean": null,
  "is_alias_email": false,
  "mx_provider_label": null,
  "deliverability_score": 0
}
```

## Response Fields

- `email` — Masked email (cryptographic fingerprint of local part, domain in clear)
- `is_risky` — Primary boolean signal: true = block/flag this address
- `risk_score` — 0 (safe) to 100 (confirmed disposable/throwaway)
- `reason` — `safe` | `disposable` | `undeliverable` | `role_account`
- `is_free_provider` — True for Gmail, Yahoo, Hotmail…
- `is_corporate_email` — True for professional/company domains
- `did_you_mean` — Typo correction if detected (e.g. "gmail.com" for "gmial.com")
- `is_alias_email` — True for SimpleLogin, AnonAddy, Apple Hide My Email…
- `mx_provider_label` — Identified email infrastructure (e.g. "Google Workspace")
- `deliverability_score` — Probability of delivery (0–100), based on MX/SPF/DMARC

## Machine-Readable API Spec

Full OpenAPI 3.1.0 specification (check endpoint only):
- https://syvel.io/openapi.json

Interactive documentation (Swagger UI, requires running API):
- https://api.syvel.io/docs

## Guides

- [Introduction](https://syvel.io/docs/guides/introduction): Syvel is a REST API that detects disposable and temporary email addresses. GDPR-compliant, EU-hosted, integrable in any stack in under 5 minutes.
- [Quick Start](https://syvel.io/docs/guides/getting-started): Start detecting disposable emails in under 5 minutes. Get your API key, make your first GET /v1/check/{email} request, and start blocking throwaway addresses.
- [Authentication](https://syvel.io/docs/guides/authentication): Authenticate Syvel API requests with an API key. Bearer token format, where to find your key in the dashboard, and request header examples in curl and JavaScript.
- [Error codes](https://syvel.io/docs/guides/errors): All HTTP status codes returned by the Syvel API — 400, 401, 403, 404, 429, 500 — with JSON error body structure and troubleshooting guidance.
- [Rate limits](https://syvel.io/docs/guides/rate-limits): API rate limits and monthly request quotas by plan. Free: 100 req/month. Starter: 1,000. Pro: 10,000. Business: 100,000. Understand overage behavior (429) and log retention per tier.
- [GDPR](https://syvel.io/docs/guides/gdpr): Syvel API GDPR compliance — EU hosting, no personal data retained after the request, legal basis for processing, and data flow documentation for DPAs.

## API Reference

- [Email check](https://syvel.io/docs/api/check): API reference for GET /v1/check/{email} — detect disposable and temporary email addresses. Returns risk_score, is_risky, reason, and deliverability_score.
- [Public endpoints](https://syvel.io/docs/api/public): Domain-level risk intelligence — check if a domain hosts disposable emails, get the list of most-blocked domains. No authentication required.

## Integrations

- [JavaScript (Fetch)](https://syvel.io/docs/integrations/javascript-fetch): Detect disposable and temporary emails in JavaScript using the native Fetch API — no npm package needed. Works in browsers and Node.js 18+, with React hook examples.
- [Node.js SDK](https://syvel.io/docs/integrations/nodejs): Official Syvel SDK for Node.js — preview the @syvel/node API for Express, Fastify, and Next.js.
- [Python (httpx / requests)](https://syvel.io/docs/integrations/python-httpx): Detect disposable and temporary emails in Python without any SDK — using httpx or requests. Includes Django REST Framework, FastAPI, and Flask examples.
- [JavaScript SDK](https://syvel.io/docs/integrations/javascript): JavaScript SDK for Syvel disposable email detection — preview the planned @syvel/js API for browser and Node.js TypeScript integration.
- [Python SDK](https://syvel.io/docs/integrations/python): Python SDK for Syvel disposable email detection — preview the planned syvel package for Django, FastAPI, and Flask integration.
- [Shopify](https://syvel.io/docs/integrations/shopify): Block disposable and temporary emails at Shopify registration and checkout.
- [WordPress](https://syvel.io/docs/integrations/wordpress): Block disposable and temporary emails in WordPress forms — Contact Form 7, WPForms, Gravity Forms, and WooCommerce.
- [Zapier](https://syvel.io/docs/integrations/zapier): Automate disposable email filtering with Zapier and Syvel — connect to CRMs, marketing tools, and thousands of apps without writing code.

## Raw Markdown

All documentation pages are also served as plain text (Markdown) by appending `.md` to the URL:

- https://syvel.io/docs/guides/introduction.md
- https://syvel.io/docs/guides/getting-started.md
- https://syvel.io/docs/guides/authentication.md
- https://syvel.io/docs/guides/errors.md
- https://syvel.io/docs/guides/rate-limits.md
- https://syvel.io/docs/guides/gdpr.md
- https://syvel.io/docs/api/check.md
- https://syvel.io/docs/api/public.md
- https://syvel.io/docs/integrations/javascript-fetch.md
- https://syvel.io/docs/integrations/nodejs.md
- https://syvel.io/docs/integrations/python-httpx.md
- https://syvel.io/docs/integrations/javascript.md
- https://syvel.io/docs/integrations/python.md
- https://syvel.io/docs/integrations/shopify.md
- https://syvel.io/docs/integrations/wordpress.md
- https://syvel.io/docs/integrations/zapier.md