# Pragmatic Email Validator — Full LLM Reference

> Validates that an email address meets pragmatic format and length expectations. Rejects RFC-compliant emails incompatible with modern email services and technologies.

## Why This Exists

RFC 5322 permits email formats that no major mail provider actually supports. Strict RFC compliance accepts garbage data that will hard-bounce when you try to send mail. This library validates what actual email providers accept, not what a text file from 1982 says is theoretically possible.

### What Gets Rejected (Even Though RFC Allows It)

- Quoted local parts (`" "@example.com`)
- IP address domains (`user@[127.0.0.1]`)
- Comments in addresses (`user(comment)@example.com`)
- Consecutive dots in local part
- Domains without a TLD (`user@localhost`)

## API Reference

Base URL: `https://api.pragmaticemailvalidator.com`

All responses use JSON. Errors use Problem Details ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html)).

### Validate Email

Validates an email against universal rules and the detected provider's rules. Includes DNS MX check.

```
POST /api/v1/validate
Content-Type: application/json

{"email": "user@gmail.com"}
```

Or via query string:

```
GET /api/v1/validate?email=user@gmail.com
```

#### Response

```json
{
  "email": "user@gmail.com",
  "isValid": true,
  "passedUniversalRules": true,
  "detectedProvider": {
    "providerId": "google-mail",
    "displayName": "Google Mail (Gmail)",
    "category": "MailboxHost"
  },
  "universalFailures": [],
  "providerFailures": [],
  "dnsCheck": {
    "domainExists": true,
    "hasMxRecords": true,
    "mxHosts": ["gmail-smtp-in.l.google.com", "..."]
  },
  "subaddress": null,
  "canonicalAddress": null,
  "asciiDomain": null,
  "tldInfo": {
    "tld": "COM",
    "type": "gTLD",
    "countryCode": null,
    "countryName": null,
    "flagEmoji": null,
    "brandName": null,
    "sponsor": "VeriSign Global Registry Services",
    "registrationModel": "open",
    "isRepurposed": false,
    "notes": null
  }
}
```

#### Subaddressing Example

When the email contains a subaddress (e.g., `user+promo@gmail.com`), the response includes:

```json
{
  "subaddress": {
    "baseLocalPart": "user",
    "subaddressTag": "promo",
    "routesTo": "user@gmail.com"
  },
  "canonicalAddress": "user@gmail.com"
}
```

#### Validation Failure Example

```json
{
  "email": "ab@gmail.com",
  "isValid": false,
  "passedUniversalRules": true,
  "detectedProvider": {
    "providerId": "google-mail",
    "displayName": "Google Mail (Gmail)",
    "category": "MailboxHost"
  },
  "universalFailures": [],
  "providerFailures": [
    {
      "ruleId": "provider-local-part-too-short",
      "message": "Local part 'ab' is 2 characters; Google Mail (Gmail) requires at least 6",
      "documentation": {
        "url": "https://support.google.com/a/answer/9193374",
        "description": "Google Workspace admin help: Username character guidelines"
      }
    }
  ]
}
```

### Matrix Validation

Validates an email against ALL supported providers at once. Useful for understanding compatibility across providers.

```
POST /api/v1/validate/matrix
Content-Type: application/json

{"email": "user@example.com"}
```

Or via query string:

```
GET /api/v1/validate/matrix?email=user@example.com
```

#### Response

```json
{
  "email": "user@example.com",
  "passedUniversalRules": true,
  "universalFailures": [],
  "detectedProviderId": null,
  "dnsCheck": { "domainExists": true, "hasMxRecords": true, "mxHosts": ["..."] },
  "results": [
    {
      "providerId": "google-mail",
      "displayName": "Google Mail (Gmail)",
      "category": "MailboxHost",
      "isDetected": false,
      "isApplicable": true,
      "isValid": false,
      "failures": [
        {
          "ruleId": "provider-local-part-too-short",
          "message": "Local part 'user' is 4 characters; Google Mail (Gmail) requires at least 6",
          "documentation": { "url": "https://support.google.com/a/answer/9193374", "description": "..." }
        }
      ],
      "subaddress": null,
      "canonicalAddress": null
    }
  ]
}
```

### List Providers

Returns all supported email providers with their validation rules.

```
GET /api/v1/providers
```

#### Response

```json
{
  "providers": [
    {
      "providerId": "google-mail",
      "displayName": "Google Mail (Gmail)",
      "category": "MailboxHost",
      "domainScope": "FixedDomainOnly",
      "addressScope": "MailboxAccounts",
      "supportsCustomDomains": false,
      "fixedDomains": ["gmail.com", "googlemail.com"],
      "mxMatchPattern": null,
      "documentation": [
        {
          "url": "https://support.google.com/a/answer/9193374",
          "description": "Google Workspace admin help: Username character guidelines"
        }
      ],
      "rules": {
        "minLocalPartLength": 6,
        "maxLocalPartLength": 30,
        "allowedCharsPattern": "a-z0-9.",
        "allowInternationalized": false,
        "allowConsecutiveDots": false,
        "allowLeadingDot": false,
        "allowTrailingDot": false,
        "subaddressDelimiter": "+",
        "subaddressingMode": "Supported",
        "dotsAreSignificant": false,
        "ignoredCharactersForCanonicalization": ".",
        "caseSensitive": false,
        "maxEmailLength": 41,
        "maxEmailFormula": "30 + 1(@) + len('gmail.com')=9 + 1(.)=1"
      }
    }
  ],
  "totalCount": 12
}
```

### Get Provider by ID

```
GET /api/v1/providers/{providerId}
```

Returns the same `ProviderDetailsResponse` shape as a single item from the list.

### Export Providers

```
GET /api/v1/providers/export?format=jsonl
GET /api/v1/providers/export?format=csv
```

Exports all providers with calculated max email lengths.

## Provider Categories

- **MailboxHost** — Providers that host mailboxes (Gmail, Outlook.com, Yahoo Mail, iCloud Mail, Proton Mail, Fastmail, Zoho Mail)
- **IdentityNotifier** — Systems that send notifications but don't host mailboxes (Auth0, Firebase Auth)
- **DeliveryInfrastructure** — Relay, gateway, and security services (Microsoft 365, Google Workspace, Mimecast, Proofpoint)

## Domain Scope

- **FixedDomainOnly** — Provider operates only on known fixed domains (e.g., `gmail.com`, `yahoo.com`)
- **CustomDomainCapable** — Provider can serve any custom domain (e.g., Google Workspace, Microsoft 365)

## Rate Limiting

The API enforces rate limiting per IP: 100 requests per 60-second window. When rate limited, a `429 Too Many Requests` response is returned with a `Retry-After` header.

## Error Format

All errors use Problem Details (RFC 9457):

```json
{
  "type": "https://pragmaticemailvalidator.com/errors/invalid-email-format",
  "title": "Invalid email format",
  "status": 400,
  "detail": "The email parameter is required and cannot be empty",
  "instance": "/api/v1/validate"
}
```

## Source Code

- GitHub: [devpartners/pragmatic-email-validator](https://github.com/devpartners/pragmatic-email-validator)
- Language: C# / .NET 10 (core library + API)
- Frontend: React / TypeScript / Vite
- Deployed on: Azure Container Apps (API) + Azure Static Web Apps (frontend)
- License: MIT