Authentication

API key management and access scopes

API Keys

API keys are used to authenticate your requests. They start with jm_live_ for production or jm_test_ for testing.

Create an API Key

1. Log in to JunkMail (Business plan required)
2. Go to "API Keys"
3. Click "Create a key"
4. Give your key a name
5. Select the required scopes
6. Copy the key (displayed only once)

Available Scopes

Scope	Description
emails:read	Read addresses and emails
emails:write	Create/delete addresses and send emails
analytics:read	Access statistics
domains:read	Read custom domains
domains:manage	Manage custom domains
webhooks:manage	Manage webhooks
forwarding:manage	Manage forwarding addresses and rules

Usage

Include your API key in the Authorization header:

curl -X GET https://api.junkmail.dev/api/v1/addresses \
  -H "Authorization: Bearer jm_live_xxxxxxxxxxxx"

JavaScript

const response = await fetch('https://api.junkmail.dev/api/v1/addresses', {
  headers: {
    'Authorization': 'Bearer jm_live_xxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
});

Python

import requests

response = requests.get(
    'https://api.junkmail.dev/api/v1/addresses',
    headers={
        'Authorization': 'Bearer jm_live_xxxxxxxxxxxx',
        'Content-Type': 'application/json',
    }
)

Revoke a Key

For security reasons, you can revoke an API key:

1. Go to "API Keys"
2. Find the key to revoke
3. Click "Revoke"
4. Confirm the revocation

Important: Once revoked, the key can no longer be used and cannot be recovered.

Best Practices

• Never share your API keys
• Use environment variables
• Create separate keys per environment (dev, prod)
• Use the minimum required scopes
• Revoke unused keys