Authentication

Authenticate your API requests using Bearer token authentication with your API key.

API Keys

Veil Mail uses API keys to authenticate requests. You can create and manage your API keys in the dashboard under Settings → API Keys.

TEST
veil_test_xxxxx

Test keys are for development. Emails are validated but not actually sent. Use test keys during development to avoid sending real emails.

LIVE
veil_live_xxxxx

Live keys are for production. Emails are sent to real recipients. Keep your live keys secure and never commit them to version control.

Making Authenticated Requests

Include your API key in the Authorization header as a Bearer token:

curl https://api.veilmail.xyz/v1/emails \
  -H "Authorization: Bearer veil_live_xxxxx" \
  -H "Content-Type: application/json"

Using the SDK, authentication is handled automatically:

auth-example.ts
import { VeilMail } from '@veilmail/sdk';

// Pass your API key when creating the client
const client = new VeilMail('veil_live_xxxxx');

// All subsequent requests are authenticated
const emails = await client.emails.list();

Security Best Practices

Use environment variables

Store your API keys in environment variables, not in your code.

# .env
VEILMAIL_API_KEY=veil_live_xxxxx

# Your code
const client = new VeilMail(process.env.VEILMAIL_API_KEY);

Never expose keys client-side

API keys should only be used on the server. Never include them in client-side code or expose them in browser requests.

Rotate keys regularly

Periodically rotate your API keys and revoke any unused keys. You can create multiple keys for different services.

Use test keys for development

Always use test keys during development to avoid accidentally sending emails to real recipients.

Authentication Errors

If authentication fails, the API returns a 401 Unauthorized response:

{
  "error": {
    "code": "authentication_error",
    "message": "Invalid API key provided"
  }
}

Common authentication issues

  • • Missing or malformed Authorization header
  • • Using a test key where a live key is required
  • • API key has been revoked or deleted
  • • API key does not have required permissions

Rate Limiting

API requests are rate limited based on your plan. Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

If you exceed the rate limit, you will receive a 429 Too Many Requests response. The Retry-After header indicates when you can retry.