Quick Start Guide
Get started with API Shield in minutes. Follow this step-by-step guide to integrate disposable email detection into your application.
Getting Started
This guide will walk you through integrating API Shield into your application in just a few minutes.
Step 1: Get Your API Key
First, you'll need an API key to authenticate your requests.
- Sign up for a free account
- Navigate to your dashboard
- Generate a new API key
- Copy and securely store your API key
Keep Your API Key Secret
Never expose your API key in client-side code or commit it to version control. Use environment variables to store your key securely.
Step 2: Make Your First Request
Let's make a simple request to check if an email is disposable:
curl "https://bifrost.api-armor.com/v1/check?email=test@example.com" \
-H "Authorization: Bearer aa_abc123xyz789"Step 3: Handle the Response
The API returns a simple JSON response:
{
"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 email is from a disposable domain, false otherwise |
domain | string | The domain extracted from the email address |
Step 4: Integrate Into Your Application
Here's a complete example of integrating API Shield into a signup form:
import { useState } from 'react';
function SignupForm() {
const [email, setEmail] = useState('');
const [error, setError] = useState('');
const [loading, setLoading] = useState(false);
const validateEmail = async (email) => {
try {
const response = await fetch(
`https://bifrost.api-armor.com/v1/check?email=${encodeURIComponent(email)}`,
{
headers: {
'Authorization': `Bearer ${process.env.NEXT_PUBLIC_API_SHIELD_KEY}`
}
}
);
const data = await response.json();
if (data.is_disposable) {
setError('Please use a valid email address. Disposable emails are not allowed.');
return false;
}
return true;
} catch (err) {
console.error('Email validation error:', err);
return true; // Fail open - don't block signup on API errors
}
};
const handleSubmit = async (e) => {
e.preventDefault();
setError('');
setLoading(true);
const isValid = await validateEmail(email);
if (isValid) {
// Proceed with signup
console.log('Email is valid, proceeding with signup...');
}
setLoading(false);
};
return (
<form onSubmit={handleSubmit}>
<input
type="email"
value={email}
onChange={(e) => setEmail(e.target.value)}
placeholder="Enter your email"
required
/>
{error && <p className="error">{error}</p>}
<button type="submit" disabled={loading}>
{loading ? 'Validating...' : 'Sign Up'}
</button>
</form>
);
}Best Practice: Fail Open
If the API is unreachable or returns an error, it's recommended to "fail open" - allow the signup to proceed rather than blocking legitimate users. You can log these cases for later review.
Step 5: Test Your Integration
Test with known disposable email providers:
- ✅ Valid:
user@gmail.com,user@outlook.com,user@company.com - ❌ Disposable:
layohe8924@badfist.com,user@tempmail.com,test@guerrillamail.com