Classify Endpoint

The classify endpoint analyzes an email address or domain and returns provider information and classification details.

Request

GET /v1/classify

Query parameters

| Parameter | Type | Required | Description | |---|---|---|---| | email | string | Yes* | The email address to classify | | domain | string | Yes* | The domain to classify |

*At least one of email or domain must be provided. If both are provided, the domain from the email takes precedence.

Examples

# Classify by email
curl -H "Authorization: Bearer sk_live_YOUR_KEY" \
  "https://api.emailclassifier.com/v1/[email protected]"

# Classify by domain
curl -H "Authorization: Bearer sk_live_YOUR_KEY" \
  "https://api.emailclassifier.com/v1/classify?domain=google.com"

Response

{
  "data": {
    "email": "[email protected]",
    "domain": "gmail.com",
    "provider": {
      "id": "gmail",
      "name": "Gmail",
      "type": "personal"
    },
    "classification": {
      "is_business": false,
      "is_free": true,
      "is_disposable": false,
      "is_custom_domain": false
    },
    "confidence": 0.99,
    "cached": true
  },
  "request_id": "req_abc123"
}

Response fields

| Field | Type | Description | |---|---|---| | email | string | The submitted email (empty if domain-only request) | | domain | string | The domain that was analyzed | | provider.id | string | Unique provider identifier | | provider.name | string | Human-readable provider name | | provider.type | string | One of: business, personal, disposable, hosting, education, self_hosted, unknown | | classification.is_business | boolean | True if the email is a business/work email | | classification.is_free | boolean | True if using a free email provider | | classification.is_disposable | boolean | True if using a disposable/temporary email service | | classification.is_custom_domain | boolean | True if using a custom domain with a known provider | | confidence | number | Confidence score from 0.0 to 1.0 | | cached | boolean | Whether the result came from cache |

Provider types

| Type | Description | Examples | |---|---|---| | business | Business email provider | Google Workspace, Microsoft 365 | | personal | Free personal email | Gmail, Outlook.com, Yahoo Mail | | disposable | Temporary/throwaway email | Guerrilla Mail, Mailinator | | hosting | Hosting provider email | GoDaddy, OVH, Namecheap | | education | Educational institution | University email systems | | self_hosted | Self-hosted mail server | Custom MX records | | unknown | Cannot be determined | No MX records found |

Headers

The response includes the following headers:

| Header | Description | |---|---| | X-Request-ID | Unique request identifier | | X-Cache | HIT if the DNS result was cached, MISS otherwise | | X-RateLimit-Limit | Your plan's rate limit per minute | | X-RateLimit-Remaining | Remaining requests in the current window | | X-RateLimit-Reset | Unix timestamp when the rate limit resets |