API Reference
Check Email
Verify if an email address uses a disposable or temporary domain.
Check Email Endpoint
GET
https://bifrost.api-armor.com/v1/checkChecks whether an email address uses a disposable, temporary, or throwaway domain.
Parameters
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
email | string | Yes | The email address to check. Must be a valid email format. |
Request Examples
curl "https://bifrost.api-armor.com/v1/check?email=layohe8924@badfist.com" \
-H "Authorization: Bearer aa_abc123xyz789"Response
Success Response
200 OKReturns information about the email address and whether it's from a disposable domain.
{
"email": "layohe8924@badfist.com",
"is_disposable": true,
"domain": "badfist.com"
}Response Fields
| Field | Type | Description |
|---|---|---|
email | string | The email address that was checked |
is_disposable | boolean | true if the domain is identified as disposable, false otherwise |
domain | string | The domain portion of the email address |
Example Responses
Disposable Email:
{
"email": "user@tempmail.com",
"is_disposable": true,
"domain": "tempmail.com"
}Legitimate Email:
{
"email": "user@gmail.com",
"is_disposable": false,
"domain": "gmail.com"
}Error Responses
Invalid Email Format
400 Bad Request{
"error": "invalid_email",
"message": "The provided email address is not valid"
}Missing Email Parameter
400 Bad Request{
"error": "missing_parameter",
"message": "The 'email' parameter is required"
}Unauthorized
401 Unauthorized{
"error": "unauthorized",
"message": "Invalid or missing API key"
}Rate Limit Exceeded
429 Too Many Requests{
"error": "rate_limit_exceeded",
"message": "Rate limit exceeded. Please try again later.",
"retry_after": 60
}Rate Limit Headers
When you receive a 429 error, check the X-RateLimit-Reset header to see when you can make requests again.
Integration Examples
Form Validation
import { useState } from 'react';
function EmailInput({ onValidate }) {
const [email, setEmail] = useState('');
const [isChecking, setIsChecking] = useState(false);
const [error, setError] = useState('');
const checkEmail = async (email) => {
setIsChecking(true);
setError('');
try {
const response = await fetch(
`https://bifrost.api-armor.com/v1/check?email=${encodeURIComponent(email)}`,
{
headers: {
'Authorization': `Bearer ${process.env.REACT_APP_API_SHIELD_KEY}`
}
}
);
const data = await response.json();
if (data.is_disposable) {
setError('Disposable email addresses are not allowed');
return false;
}
return true;
} catch (err) {
console.error('Email check failed:', err);
return true; // Fail open
} finally {
setIsChecking(false);
}
};
const handleBlur = async () => {
if (email) {
const isValid = await checkEmail(email);
onValidate?.(email, isValid);
}
};
return (
<div>
<input
type="email"
value={email}
onChange={(e) => setEmail(e.target.value)}
onBlur={handleBlur}
disabled={isChecking}
/>
{isChecking && <span>Checking...</span>}
{error && <span className="error">{error}</span>}
</div>
);
}Best Practices
1. Fail Open
If the API is unavailable, allow the request to proceed rather than blocking users:
def is_disposable_email(email):
try:
# API call with timeout
result = check_email_api(email, timeout=5)
return result['is_disposable']
except Exception as e:
# Log error but don't block user
logger.error(f"Email check failed: {e}")
return False # Fail open2. Async Validation
For better UX, validate emails asynchronously after submission:
async function handleSignup(userData) {
// Create user account immediately
const user = await createUser(userData);
// Check email asynchronously
checkEmail(userData.email).then(result => {
if (result.is_disposable) {
// Flag account for review
flagAccountForReview(user.id);
sendWarningEmail(user.email);
}
});
return user;
}