Authentication
Learn how to authenticate your API requests to Mailhooks using API keys.
Overview
Mailhooks uses API keys to authenticate requests. You can create and manage API keys from your dashboard. All API requests must include your API key in the request headers.
Creating an API Key
Log in to your Mailhooks dashboard
Navigate to API Keys
Click "Create API Key"
Give your key a descriptive name
Copy and securely store your API key
Using Your API Key
Include your API key in the x-api-key header with all API requests:
curl -H "x-api-key: mh_your_api_key_here" \
https://mailhooks.dev/api/v1/emailsCode Examples
JavaScript/Node.js
const response = await fetch('https://mailhooks.dev/api/v1/emails', {
headers: {
'x-api-key': process.env.MAILHOOKS_API_KEY,
'Content-Type': 'application/json'
}
});
const emails = await response.json();TypeScript SDK Recommended
Install: npm install @mailhooks/sdk
import { Mailhooks } from '@mailhooks/sdk';
const mailhooks = new Mailhooks({
apiKey: process.env.MAILHOOKS_API_KEY
});
// Type-safe API calls with autocomplete
const emails = await mailhooks.emails.list({
page: 1,
perPage: 20
});
// Get specific email
const email = await mailhooks.emails.get('email-id');Python
import requests
import os
headers = {
'x-api-key': os.environ.get('MAILHOOKS_API_KEY'),
'Content-Type': 'application/json'
}
response = requests.get('https://mailhooks.dev/api/v1/emails', headers=headers)
emails = response.json()API Key Management
Manage your API keys programmatically through the API.
List API Keys
GET https://mailhooks.dev/api/v1/api-keysResponse
{
"data": [
{
"id": "ak_1234567890",
"name": "Production API Key",
"prefix": "mh_abc...",
"active": true,
"environmentId": "env_123",
"lastUsedAt": "2024-01-15T10:30:00Z",
"expiresAt": null,
"createdAt": "2024-01-01T00:00:00Z"
}
],
"currentPage": 1,
"perPage": 20,
"totalItems": 1,
"totalPages": 1,
"hasNextPage": false
}Response Fields
| Field | Type | Description |
|---|---|---|
id | string | Unique API key identifier |
name | string | Descriptive name for the API key |
prefix | string | Partial key for identification (first 8 chars) |
active | boolean | Whether the key is currently active |
environmentId | string? | Environment the key is scoped to (null = all environments) |
lastUsedAt | string? | ISO 8601 timestamp of last API request |
expiresAt | string? | ISO 8601 expiration timestamp (null = no expiry) |
createdAt | string | ISO 8601 timestamp when key was created |
Delete API Key
DELETE https://mailhooks.dev/api/v1/api-keys/:idcurl -X DELETE https://mailhooks.dev/api/v1/api-keys/ak_1234567890 \
-H "x-api-key: mh_your_api_key_here"Activate / Deactivate API Key
Temporarily disable an API key without deleting it, or re-enable a deactivated key.
Activate
POST https://mailhooks.dev/api/v1/api-keys/:id/activateDeactivate
POST https://mailhooks.dev/api/v1/api-keys/:id/deactivateSecurity Best Practices
Environment Variables
Store API keys in environment variables, not in code
Client-Side Security
Never expose API keys in client-side JavaScript
Environment Separation
Use different API keys for dev, staging, and production
Key Rotation
Rotate API keys regularly for enhanced security
Quick Response
Immediately deactivate compromised keys
HTTPS Only
Always use HTTPS for all API requests
Rate Limits
API requests are rate limited to ensure fair usage:
Free Tier
100
requests per minute
Pro Tier
1,000
requests per minute
Rate limit information in response headers:
X-RateLimit-Limit- Request limit per minuteX-RateLimit-Remaining- Remaining requestsX-RateLimit-Reset- Time when limit resets