Authentication

Learn how to authenticate your API requests to ValidMail. All API requests require authentication using an API key.

API Keys

API keys are used to authenticate your requests to the ValidMail API. Each key is associated with your account and can be managed from your dashboard.

Creating an API Key

1. Go to your Dashboard
2. Navigate to the "API Keys" section
3. Click "Create New Key"
4. Give your key a descriptive name (e.g., "Production", "Development")
5. Copy the key immediately - it won't be shown again

Using Your API Key

Include your API key in the Authorization header of every request using the Bearer token format.

Header Format

Authorization: Bearer YOUR_API_KEY

Example Request

curl -X POST https://validmail.io/api/v1/verify \
  -H "Authorization: Bearer vm_live_abc123xyz789..." \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'

API Key Types

ValidMail provides two types of API keys for different environments:

Live Keys

Use live keys for production environments. These keys consume your verification credits.

vm_live_...

Test Keys

Use test keys for development and testing. These keys return mock responses and don't consume credits.

vm_test_...

Security Best Practices

Never expose API keys

Never include API keys in client-side code, public repositories, or anywhere they could be exposed. Always make API calls from your server.

Use environment variables

Store API keys in environment variables, never in your codebase.

VALIDMAIL_API_KEY=vm_live_abc123xyz789...

Use separate keys for environments

Create separate API keys for development, staging, and production environments.

Rotate keys regularly

Periodically rotate your API keys and revoke any that may have been compromised.

Monitor usage

Regularly check your dashboard for unusual API usage patterns that might indicate a compromised key.

Authentication Errors

If authentication fails, the API returns an error response:

Status	Error	Description
401	MISSING_API_KEY	No API key provided in the request
401	INVALID_API_KEY	The provided API key is invalid or revoked
403	INSUFFICIENT_CREDITS	Account has no remaining verification credits
429	RATE_LIMITED	Too many requests - please slow down

Error Response Example

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked",
    "status": 401
  }
}

Rate Limits

API requests are rate limited based on your plan:

Plan	Requests/Second	Requests/Day
Free	1	100
Starter	10	10,000
Professional	50	100,000
Enterprise	Custom	Unlimited

Rate limit information is included in response headers:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 1640000000