Authentication
All API requests require authentication via an API key passed in the Authorization header.
API Key format
Keys use the format sk_live_ followed by 64 hex characters:
sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789...
Using your key
Include the key in the Authorization header with the Bearer scheme:
cURL
curl -H "Authorization: Bearer sk_live_YOUR_KEY" \
"https://emailkind.com/v1/classify?email=test@gmail.com"
JavaScript
const response = await fetch(
"https://emailkind.com/v1/classify?email=test@gmail.com",
{
headers: {
Authorization: "Bearer sk_live_YOUR_KEY",
},
}
);
const data = await response.json();
Python
import requests
response = requests.get(
"https://emailkind.com/v1/classify",
params={"email": "test@gmail.com"},
headers={"Authorization": "Bearer sk_live_YOUR_KEY"}
)
data = response.json()
PHP
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => "https://emailkind.com/v1/classify?email=test@gmail.com",
CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_live_YOUR_KEY"],
CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
Go
req, _ := http.NewRequest("GET", "https://emailkind.com/v1/classify?email=test@gmail.com", nil)
req.Header.Set("Authorization", "Bearer sk_live_YOUR_KEY")
resp, err := http.DefaultClient.Do(req)
Ruby
uri = URI("https://emailkind.com/v1/classify?email=test@gmail.com")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer sk_live_YOUR_KEY"
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
Getting a key programmatically
AI agents and scripts can obtain their own key without a browser. Two requests, anchored on control of a mailbox.
Step 1 — request a code
POST /v1/signup
Content-Type: application/json
{"email": "you@example.com", "lang": "en"}
{
"success": true,
"request_id": "req_a1b2c3d4e5f6",
"status": "verification_sent",
"expires_in": 900,
"next": "POST /v1/signup/confirm",
"message": "A confirmation code was sent to that address..."
}
An 8-character code is emailed to the address. Nothing is stored at this point: no account exists until the code comes back, so an abandoned signup leaves nothing behind.
The response is identical whether or not the address already has an account — the endpoint cannot be used to find out who has one.
lang is optional (en or fr) and only sets the language of the email.
Step 2 — exchange it for a key
POST /v1/signup/confirm
Content-Type: application/json
{"email": "you@example.com", "code": "K7M2QXAB"}
{
"success": true,
"request_id": "req_a1b2c3d4e5f6",
"api_key": "sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
"plan": "free",
"monthly_limit": 100,
"burst_limit": 10,
"docs": "https://emailkind.com/docs/getting-started",
"warning": "This key is shown once and is not recoverable..."
}
The code is case-insensitive, and spaces or dashes in it are ignored. If the address has no account yet, one is created and already verified — the code proved the mailbox, so there is no separate verification email.
The key is a normal live key, identical to one created in the dashboard. It is returned once and never again. Store it as a secret: unlike a dashboard key, this one passes through your logs on the way in.
Limits and errors
| Limit | Value | |---|---| | Code validity | 15 minutes | | Attempts per code | 5, then the signup is cancelled | | Signups started | 5 per hour per IP | | Codes emailed | 3 per hour per address |
| Code | Status | Meaning |
|---|---|---|
| INVALID_BODY | 400 | Body is not JSON, or a required field is missing |
| INVALID_EMAIL | 400 | The address is malformed or has no real TLD |
| DISPOSABLE_EMAIL | 400 | The domain is a disposable mail provider |
| UNDELIVERABLE_EMAIL | 400 | The mail provider rejected the address |
| INVALID_CODE | 400 | The code is wrong, expired, or was never issued |
| KEY_LIMIT_REACHED | 409 | The account already holds the maximum keys for its plan |
| RATE_LIMITED | 429 | Too many signups from this IP, or too many codes to this address |
| TOO_MANY_ATTEMPTS | 429 | Five wrong codes; the signup was cancelled |
| SIGNUP_UNAVAILABLE | 503 | Signup is temporarily down; use the web form or retry |
An expired code and one that never existed share INVALID_CODE: once the record has expired there is nothing left to tell them apart.
Accounts created this way have no password
The signup proved a mailbox, not a password, so the account starts without one. To sign in to the dashboard, use Forgot password on the login page to set one — it works on these accounts normally.
Key management
You can manage your API keys from the Dashboard:
- Create new keys with descriptive names (e.g., "Production", "Staging")
- Revoke keys that are compromised or no longer needed
- View key prefixes and last usage timestamps
Security best practices
| Do | Don't | |---|---| | Store keys in environment variables | Commit keys to source control | | Use different keys per environment | Share keys between applications | | Revoke unused keys | Log full API keys | | Rotate keys periodically | Expose keys in client-side code |
Key limits by plan
| Plan | Max API keys | |---|---| | Free | 1 | | Starter | 3 | | Growth | 5 | | Scale | 10 |
IP Allowlisting
You can restrict each API key to specific IP addresses for added security. When configured, requests from non-allowed IPs will be rejected with a 403 Forbidden response.
How to configure
- Go to Dashboard > API Keys
- Click the IPs button next to your key
- Enter one IP address or CIDR range per line
- Click Save IP restrictions
Supported formats
| Format | Example | Description |
|---|---|---|
| IPv4 | 203.0.113.1 | Single IP address |
| IPv6 | 2001:db8::1 | Single IPv6 address |
| CIDR | 10.0.0.0/8 | IP range (all 10.x.x.x) |
| CIDR v6 | 2001:db8::/32 | IPv6 range |
Leave the list empty to allow requests from any IP (default).
Error response
{
"success": false,
"error": {
"code": "IP_NOT_ALLOWED",
"message": "Your IP address is not in the allowlist for this API key"
}
}
Webhooks
EmailKind can notify your application via webhooks when a domain's classification changes. This is useful for keeping your data up-to-date without polling.
Setup
- Go to Dashboard > Webhooks
- Enter your endpoint URL (HTTPS recommended)
- Copy and store the signing secret securely
Events
| Event | Description |
|---|---|
| domain.changed | A domain's provider type has changed since the last classification |
Payload format
{
"event": "domain.changed",
"timestamp": "2025-01-15T10:30:00Z",
"data": {
"domain": "example.com",
"old_type": "business",
"new_type": "disposable",
"provider_id": "mailinator",
"provider_name": "Mailinator"
}
}
Verifying signatures
Each webhook request includes an X-EmailKind-Signature header containing an HMAC-SHA256 signature of the payload body:
X-EmailKind-Signature: sha256=5d41402abc4b2a76b9719d911017c592...
Verify the signature using your signing secret:
import hmac, hashlib
def verify_signature(payload, signature, secret):
expected = "sha256=" + hmac.new(
secret.encode(), payload, hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature)
Error responses
If authentication fails, you'll receive a 401 Unauthorized response:
{
"success": false,
"request_id": "req_abc123",
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
}