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

Navigate to API Keys

Click "Create API Key"

Give your key a descriptive name

Copy and securely store your API key

Important: Your API key will only be shown once. Store it securely and never expose it in client-side code or public repositories.

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" \
     http://localhost:3000/api/v1/emails

Code Examples

JavaScript/Node.js

const response = await fetch('http://localhost:3000/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');

View on NPM →

Python

import requests
import os

headers = {
    'x-api-key': os.environ.get('MAILHOOKS_API_KEY'),
    'Content-Type': 'application/json'
}

response = requests.get('http://localhost:3000/api/v1/emails', headers=headers)
emails = response.json()

Security 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