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" \
     undefined/api/v1/emails

Code Examples

JavaScript/Node.js

const response = await fetch('undefined/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('undefined/api/v1/emails', headers=headers)
emails = response.json()

API Key Management

Manage your API keys programmatically through the API.

List API Keys

GET undefined/api/v1/api-keys

Response

{
  "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 undefined/api/v1/api-keys/:id

curl -X DELETE undefined/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 undefined/api/v1/api-keys/:id/activate

Deactivate

POST undefined/api/v1/api-keys/:id/deactivate

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