Disposable Armor API Documentation

The Disposable Armor API makes it easy to detect disposable/temporary email domains in your applications. This documentation covers everything you need to know to integrate with our API.

Get API Key

View Pricing

Authentication

All requests to the Disposable Armor API require authentication with your API key. You can create and manage multiple API keys from your dashboard after creating an account.

API Key in Header

You can include your API key in the request headers:

Authorization: Bearer YOUR_API_KEY
// OR
X-API-Key: YOUR_API_KEY

Multiple API Keys

You can create multiple API keys for different applications or environments. All keys share the same monthly quota for your account.

Plan	Max API Keys
Free	1
Basic	3
Pro	7
Plus	10
Growth	25
Enterprise	Unlimited

Rate Limits

Our API has two types of rate limits to ensure fair usage and system stability:

1. Monthly Quotas

API quotas are based on your subscription plan and reset on your billing anniversary date each month.

Plan	Monthly Quota	Price
Free	100 checks	Free
Basic	3,000 checks	$1.99/month
Pro	15,000 checks	$4.99/month
Plus	30,000 checks	$8.99/month
Growth	150,000 checks	$29.99/month
Enterprise	Custom checks	Custom

2. Technical Rate Limit

To protect against abuse, all API keys are limited to 60 requests per minute regardless of your plan.

Note: If you exceed either limit, you'll receive a 429 status code with details about which limit was exceeded.

API Endpoints

Check a Domain or Email

This endpoint checks if a domain or email address is from a disposable/temporary email service.

GET /api/v1/check

Provide domain or email as the query parameter. If email is provided, the server extracts the domain automatically.

# Using a domain
curl -X GET "https://www.disposablearmor.com/api/v1/check?domain=mailinator.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Using an email (server extracts the domain)
curl -X GET "https://www.disposablearmor.com/api/v1/[email protected]" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

Parameter	Type	Description
`domain`	string	A domain to check, e.g. `mailinator.com`
`email`	string	An email address. The server extracts and checks the domain part only.

Response Format

Basic response (all plans):

{
  "domain": "mailinator.com",
  "is_temporary": true,
  "is_allowed": false,
  "checks_remaining": 2950,
  "monthly_limit": 3000,
  "reset_date": "2025-01-31"
}

Enhanced response (paid plans only):

{
  "domain": "mailinator.com",
  "is_temporary": true,
  "is_allowed": false,
  "checks_remaining": 14950,
  "limit": 15000,
  "reset_date": "2025-01-31",
  "advanced_check": {
    "performed": true,
    "result": true,
    "error": null
  },
  "apple_proxy_detection": {
    "is_apple_proxy": false,
    "proxy_type": null,
    "confidence": "high",
    "confidence_score": 5,
    "details": {
      "reasoning": "IP not in Apple Private Relay ranges"
    },
    "description": "No Apple proxy detected (5% confidence)"
  }
}

Response Fields

Field	Type	Description
`domain`	string	The domain that was checked (extracted from email if email was provided)
`is_temporary`	boolean	`true` if the domain is identified as temporary/disposable, `false` otherwise
`is_allowed`	boolean	`true` if the domain is on the allowlist (which overrides temporary status)
`checks_remaining`	number	Number of API calls remaining in your current billing period (after this call)
`limit`	number	Total monthly API call limit for your plan
`reset_date`	string	Date when your monthly quota will reset (YYYY-MM-DD format)
`advanced_check`	object	Advanced ML-based detection results (paid plans only). See detailed breakdown below.
`apple_proxy_detection`	object	Apple privacy service detection results (paid plans only). See detailed breakdown below.

Advanced Check Object (Paid Plans)

The advanced_check object contains results from machine learning-based detection:

Field	Type	Description
`performed`	boolean	Always `true` for paid plans
`result`	boolean	`true` if ML detection identifies the domain as disposable, `false` otherwise
`error`	string \| null	Error message if the check failed, `null` if successful

Apple Proxy Detection Object (Paid Plans)

The apple_proxy_detection object contains results from Apple privacy service detection:

Field	Type	Description
`is_apple_proxy`	boolean	`true` if Apple privacy service detected, `false` otherwise
`proxy_type`	string \| null	Type of Apple service detected: `"hide_my_email"`, `"private_relay"`, or `null` if none detected
`confidence`	string	Human-readable confidence level: `"high"` (90-100%), `"medium"` (70-89%), or `"low"` (0-69%)
`confidence_score`	number	Numeric confidence percentage (0-100) indicating how likely it is to be an Apple proxy. A score of 95 = 95% likely IS an Apple proxy (high detection). A score of 5 = 5% likely (95% likely NOT an Apple proxy). See explanation below for more details.
`details`	object	Additional detection details (varies by detection method)
`description`	string	Human-readable description of the detection result

Understanding Confidence Scores

The confidence_score is a percentage (0-100) that represents the likelihood that the email/IP IS an Apple proxy.

•

Score of 5: Only 5% likely to be an Apple proxy → Most likely NOT an Apple proxy (95% sure it's normal traffic)

•

Score of 50: 50/50 chance → Uncertain

•

Score of 95: 95% likely to be an Apple proxy → Very confident it IS Apple Hide My Email or Private Relay

Implementation tip: Use confidence_score > 70 to flag likely Apple proxies, or check is_apple_proxy === true for a simple boolean result.

Error Responses

The API returns appropriate HTTP status codes and error messages:

Status Code	Error Code	Description
400	invalid_input	Missing or invalid query parameter
401	invalid_api_key	Invalid or missing API key
429	monthly_limit_exceeded	Monthly API quota exceeded
429	technical_rate_limit_exceeded	Technical rate limit (60/minute) exceeded

Important Disclaimer

Accuracy Notice: While our service strives for high accuracy in detecting disposable email addresses, we cannot guarantee 100% accuracy in all cases. Email classification results should be used as guidance rather than absolute truth.

The disposable email landscape is constantly evolving, with new services appearing and existing ones changing their patterns. Our algorithms and database are continuously updated to maintain the highest possible accuracy, but false positives and false negatives may occasionally occur.

We recommend implementing appropriate fallback mechanisms and user verification processes in your applications. Disposable Armor should be used as one component of a comprehensive email validation strategy.

Ready to Get Started?

Get Your API Key