Managing API Keys

API keys let you authenticate with TrueMail’s API. You can create multiple keys for different applications or environments, and revoke them when needed.

Creating an API Key

1. Log in to your TrueMail dashboard
2. Navigate to Settings → API Keys
3. Click Create New Key
4. Give your key a descriptive name (e.g., “Production Server” or “Development”)
5. Click Create

Important: Your API key is shown only once when created. Copy it immediately and store it securely. We cannot retrieve it for you later.

API key format

TrueMail API keys follow this format:

tm_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

The tm_live_ prefix helps identify it as a TrueMail production key.

Using Your API Key

Include your API key in the Authorization header of every API request:

curl -X POST https://api.truemail.app/v1/verify \
  -H "Authorization: Bearer tm_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Common mistakes

❌ Don’t include “Bearer” twice:

Authorization: Bearer Bearer tm_live_...

❌ Don’t forget the space after Bearer:

Authorization: Bearertm_live_...

✅ Correct format:

Authorization: Bearer tm_live_...

Managing Multiple Keys

You might want separate API keys for:

• Production vs Development: Different keys for each environment
• Different applications: Separate keys for your website, mobile app, and backend
• Team members: Individual keys for tracking usage
• Third-party integrations: Dedicated keys you can revoke if needed

Naming conventions

Use clear, descriptive names:

• ✅ “Production - Main Website”
• ✅ “Development - Local Testing”
• ✅ “Zapier Integration”
• ❌ “Key 1”
• ❌ “test”

Editing API Keys

You can update an API key’s name or IP restrictions at any time:

1. Go to Settings → API Keys
2. Click the Edit button next to the key
3. Make your changes
4. Click Save

Note: You cannot view or change the key itself after creation. If you’ve lost a key, create a new one and revoke the old one.

Revoking API Keys

If a key is compromised or no longer needed, revoke it immediately:

1. Go to Settings → API Keys
2. Click the Revoke button next to the key
3. Confirm the action

Once revoked:

• The key stops working immediately
• Any requests using it will receive a 401 error
• The action cannot be undone
• The key remains in your list (marked as revoked) for reference

Security Best Practices

1. Never expose keys in client-side code

API keys should only be used server-side. Never include them in:

• JavaScript running in browsers
• Mobile app source code
• Public repositories
• Client-side config files

❌ Bad - exposed in frontend:

// Don't do this!
const API_KEY = 'tm_live_abc123...';
fetch('https://api.truemail.app/v1/verify', {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});

✅ Good - called from backend:

// Frontend calls your backend
const result = await fetch('/api/validate-email', {
  method: 'POST',
  body: JSON.stringify({ email: userEmail })
});

// Your backend calls TrueMail
// (API key stored in environment variables)

2. Use environment variables

Store API keys in environment variables, not in code:

# .env file (don't commit this!)
TRUEMAIL_API_KEY=tm_live_abc123...

# Python
import os
api_key = os.environ.get('TRUEMAIL_API_KEY')

# Ruby
api_key = ENV['TRUEMAIL_API_KEY']

// Node.js
const apiKey = process.env.TRUEMAIL_API_KEY;

3. Rotate keys periodically

Even without a breach, rotating keys periodically is good security hygiene:

1. Create a new API key
2. Update your applications to use the new key
3. Verify everything works
4. Revoke the old key

4. Use IP restrictions

For production servers with static IPs, add IP restrictions to limit where the key can be used from.

5. Monitor usage

Check your API key usage regularly. Unexpected spikes might indicate:

• A bug in your code
• Unauthorized use
• A security breach

6. Use separate keys per environment

Don’t use production keys in development. If a dev key is accidentally exposed, it won’t affect production.

Troubleshooting

“Invalid API key” error

1. Check for typos: Copy the key again from a secure location
2. Check the format: Should be Bearer tm_live_...
3. Verify it’s not revoked: Check your API keys list
4. Check IP restrictions: Your IP might not be allowed

“IP address not allowed” error

The request is coming from an IP not in the key’s allowlist. See IP Restrictions.

Lost your API key?

API keys cannot be recovered. Create a new key and update your applications.

Related

• IP Restrictions - Secure keys with IP allowlists
• API Overview - Authentication basics
• Error Handling - Handle authentication errors