Response Format

All nofakemails API responses follow a consistent JSON structure with predictable field types and values. This page covers the response formats for single email validation, batch validation, and error responses.

Field Stability

All fields in the response are guaranteed to be present. Fields that may not have a value will be null (for strings) or false (for booleans). Numeric fields default to 0.

Single Email Validation

Returned by the GET /v1/email/{email} endpoint when validating a single email address. The response contains all validation results as a flat JSON object.

{
  "email": "user@example.com",
  "valid": true,
  "normalized": "user@example.com",
  "local_part": "user",
  "alias": false,
  "ascii": true,
  "role": null,
  "gibberish": false,
  "gibberish_score": 0.12,
  "domain": "example.com",
  "mx": true,
  "disposable": false,
  "public": false,
  "relay": false,
  "typo": false,
  "typo_suggestion": null
}

Email Attributes

Field	Type	Description
`email`	string	The original email address that was validated
`valid`	boolean	Indicates whether the email address has valid format according to RFC 5322
`normalized`	string \| null	Normalized/standardized version of the email address (lowercase)
`local_part`	string \| null	The local part of the email address (before the @ symbol)
`alias`	boolean	Indicates whether the email contains a plus tag (e.g., user+tag@example.com)
`ascii`	boolean	Indicates whether the email address contains only ASCII characters
`role`	string \| null	The role category if this is a role-based email (e.g., "Admin", "Support", "Sales"). Null if not a role account.
`gibberish`	boolean	Indicates whether the email's local part appears to be randomly generated gibberish
`gibberish_score`	number	Confidence score for gibberish detection (0.0 to 1.0). Higher values indicate a higher likelihood of gibberish.

Domain Attributes

Field	Type	Description
`domain`	string \| null	The domain portion of the email address (after the @ symbol)
`mx`	boolean	Indicates whether the domain has valid MX (Mail Exchange) records configured
`disposable`	boolean	Indicates whether the domain is a known disposable/temporary email provider
`public`	boolean	Indicates whether the domain is a public email provider (Gmail, Yahoo, Outlook, etc.)
`relay`	boolean	Indicates whether the domain is an email relay/forwarding service
`typo`	boolean	Indicates whether the domain appears to be a typo of a common email provider
`typo_suggestion`	string \| null	Suggested correction if the domain appears to be a typo (e.g., "gmail.com" for "gmial.com")

Examples

Valid Gmail Address

{
  "email": "john.doe@gmail.com",
  "valid": true,
  "normalized": "john.doe@gmail.com",
  "local_part": "john.doe",
  "alias": false,
  "ascii": true,
  "role": null,
  "gibberish": false,
  "gibberish_score": 0.08,
  "domain": "gmail.com",
  "mx": true,
  "disposable": false,
  "public": true,
  "relay": false,
  "typo": false,
  "typo_suggestion": null
}

Disposable Email Detected

{
  "email": "test@mailinator.com",
  "valid": true,
  "normalized": "test@mailinator.com",
  "local_part": "test",
  "alias": false,
  "ascii": true,
  "role": null,
  "gibberish": false,
  "gibberish_score": 0.10,
  "domain": "mailinator.com",
  "mx": true,
  "disposable": true,
  "public": false,
  "relay": false,
  "typo": false,
  "typo_suggestion": null
}

Role Account Email

{
  "email": "support@example.com",
  "valid": true,
  "normalized": "support@example.com",
  "local_part": "support",
  "alias": false,
  "ascii": true,
  "role": "Support",
  "gibberish": false,
  "gibberish_score": 0.05,
  "domain": "example.com",
  "mx": true,
  "disposable": false,
  "public": false,
  "relay": false,
  "typo": false,
  "typo_suggestion": null
}

Gibberish Detected

{
  "email": "xkq7zmt9v@gmail.com",
  "valid": true,
  "normalized": "xkq7zmt9v@gmail.com",
  "local_part": "xkq7zmt9v",
  "alias": false,
  "ascii": true,
  "role": null,
  "gibberish": true,
  "gibberish_score": 0.92,
  "domain": "gmail.com",
  "mx": true,
  "disposable": false,
  "public": true,
  "relay": false,
  "typo": false,
  "typo_suggestion": null
}

Email Alias (Plus Tag)

{
  "email": "user+newsletter@example.com",
  "valid": true,
  "normalized": "user+newsletter@example.com",
  "local_part": "user+newsletter",
  "alias": true,
  "ascii": true,
  "role": null,
  "gibberish": false,
  "gibberish_score": 0.06,
  "domain": "example.com",
  "mx": true,
  "disposable": false,
  "public": false,
  "relay": false,
  "typo": false,
  "typo_suggestion": null
}

Typo Suggestion

{
  "email": "user@gmial.com",
  "valid": true,
  "normalized": "user@gmial.com",
  "local_part": "user",
  "alias": false,
  "ascii": true,
  "role": null,
  "gibberish": false,
  "gibberish_score": 0.11,
  "domain": "gmial.com",
  "mx": false,
  "disposable": false,
  "public": false,
  "relay": false,
  "typo": true,
  "typo_suggestion": "user@gmail.com"
}

Email Relay Service

{
  "email": "user@simplelogin.com",
  "valid": true,
  "normalized": "user@simplelogin.com",
  "local_part": "user",
  "alias": false,
  "ascii": true,
  "role": null,
  "gibberish": false,
  "gibberish_score": 0.11,
  "domain": "simplelogin.com",
  "mx": true,
  "disposable": false,
  "public": false,
  "relay": true,
  "typo": false,
  "typo_suggestion": null
}

Batch Validation

Returned by the POST /v1/emails endpoint when validating multiple email addresses. The response wraps individual results in a batch envelope with summary metadata.

{
  "success": true,
  "partial": false,
  "total": 3,
  "valid_count": 2,
  "invalid_count": 0,
  "error_count": 1,
  "usage_points": 3,
  "processing_time_ms": 245,
  "results": [
    {
      "email": "john.doe@gmail.com",
      "status": "success",
      "result": {
        "email": "john.doe@gmail.com",
        "valid": true,
        "normalized": "john.doe@gmail.com",
        "local_part": "john.doe",
        "alias": false,
        "ascii": true,
        "role": null,
        "gibberish": false,
        "gibberish_score": 0.08,
        "domain": "gmail.com",
        "mx": true,
        "disposable": false,
        "public": true,
        "relay": false,
        "typo": false,
        "typo_suggestion": null
      },
      "error": null
    },
    {
      "email": "test@mailinator.com",
      "status": "success",
      "result": {
        "email": "test@mailinator.com",
        "valid": true,
        "normalized": "test@mailinator.com",
        "local_part": "test",
        "alias": false,
        "ascii": true,
        "role": null,
        "gibberish": false,
        "gibberish_score": 0.10,
        "domain": "mailinator.com",
        "mx": true,
        "disposable": true,
        "public": false,
        "relay": false,
        "typo": false,
        "typo_suggestion": null
      },
      "error": null
    },
    {
      "email": "user@broken-dns.example",
      "status": "error",
      "result": null,
      "error": {
        "code": "DNS_TIMEOUT",
        "message": "DNS lookup timed out for domain"
      }
    }
  ]
}

Batch Envelope Fields

Field	Type	Description
`success`	boolean	Whether the batch validation request completed successfully
`partial`	boolean	Whether results are partial due to timeout or cancellation
`total`	integer	Total number of unique emails processed in the batch
`valid_count`	integer	Number of emails that passed format validation
`invalid_count`	integer	Number of emails that failed format validation
`error_count`	integer	Number of emails that encountered errors during validation
`usage_points`	integer	Number of usage points consumed by this batch request
`processing_time_ms`	integer	Time taken to process the batch in milliseconds
`results`	array	Per-email validation results in the same order as the input

Per-Email Result Fields

Each item in the results array contains the following fields. When status is "success", the result object contains the same fields as the single email validation response.

Field	Type	Description
`email`	string	The email address that was validated
`status`	string	Status of the validation: `"success"` or `"error"`
`result`	object \| null	The full validation result when status is `"success"`. Null when status is `"error"`.
`error`	object \| null	Error details when status is `"error"`. Contains `code` (e.g., `"DNS_TIMEOUT"`) and `message` fields. Null when status is `"success"`.

Partial Results

When the partial field is true, some emails in the batch may not have been processed due to a timeout. Always check this field and handle incomplete batches in your application logic.

Error Handling

When a request fails, the API returns a standardized error response with status, error, and code fields. See the Error Codes page for the full list of error codes and how to handle them.

Response Interface

Use these type definitions to deserialize the single email validation response in your language of choice.

response.json

{
  "email": "user@example.com",
  "valid": true,
  "normalized": "user@example.com",
  "local_part": "user",
  "alias": false,
  "ascii": true,
  "role": null,
  "gibberish": false,
  "gibberish_score": 0.12,
  "domain": "example.com",
  "mx": true,
  "disposable": false,
  "public": false,
  "relay": false,
  "typo": false,
  "typo_suggestion": null
}

Raw JSON response from the API. All fields are always present.

Role Categories

When the role field is not null, it will contain one of the following categories:

Role Category	Example Prefixes
Admin	admin, administrator, root, webmaster
Support	support, help, helpdesk, service
Sales	sales, business, partnerships
Marketing	marketing, pr, press, media
General	info, contact, hello, team
NoReply	noreply, no-reply, donotreply
Billing	billing, invoices, payments, accounts
Legal	legal, privacy, abuse, dmca
IT	postmaster, hostmaster, security
HR	hr, jobs, careers, recruiting

Common Use Cases

Blocking Disposable Emails

if (result.disposable) {
  throw new Error('Disposable email addresses are not allowed');
}

// Continue with registration
await registerUser(result.normalized);

Warning About Role Accounts

if (result.role) {
  console.warn(`Role account detected: ${result.role}`);
  // Show warning to user or allow with lower priority
}

// You might want to allow role accounts but flag them
await registerUser(result.normalized, { isRoleAccount: true });

Handling Typos

if (result.typo && result.typo_suggestion) {
  // Show suggestion to user
  const confirmed = await confirmCorrection(
    `Did you mean: ${result.typo_suggestion}?`
  );

  if (confirmed) {
    // Validate the suggested email instead
    return validateEmail(result.typo_suggestion);
  }
}

Checking Email Deliverability

if (!result.valid) {
  throw new Error('Invalid email format');
}

if (!result.mx) {
  throw new Error('Email domain cannot receive messages');
}

// Email appears deliverable
await sendEmail(result.normalized);

Filtering Aliases

if (result.alias) {
  // Some systems strip plus tags for deduplication
  const baseEmail = result.local_part.split('+')[0] + '@' + result.domain;
  console.log('Base email (without tag):', baseEmail);
}

// Or keep the full email with tag
await registerUser(result.normalized);

Detecting Gibberish Emails

if (result.gibberish) {
  // Flag emails with randomly generated local parts
  console.warn(`Gibberish email detected (score: ${result.gibberish_score})`);

  // Optionally block or require additional verification
  if (result.gibberish_score > 0.8) {
    throw new Error('Email address appears to be randomly generated');
  }
}

Processing Batch Results

const response = await fetch('/api/v1/validate/batch', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ emails }),
});

const batch = await response.json();

if (batch.partial) {
  console.warn('Batch timed out - some results may be missing');
}

for (const item of batch.results) {
  if (item.status === 'error') {
    console.error(`Failed: ${item.email} - ${item.error.message}`);
    continue;
  }

  if (item.result.disposable) {
    console.log(`Blocked: ${item.email} (disposable)`);
  }
}