Authentication

MoMail uses API keys to authenticate requests. You can create and manage API keys from your dashboard.

API Key Authentication

All API requests must include your API key in the X-API-Key header. API keys are tied to your account and determine your rate limits and access permissions.

X-API-Key: mk_xxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxx

Creating an API Key

1. Log in to your MoMail Dashboard
2. Navigate to Settings > API Keys
3. Click Create New Key
4. Enter a descriptive name
5. Optionally set an expiration date
6. Copy the key immediately

Caution

The full API key is only shown once during creation. If you lose it, you will need to create a new key.

API Key Format

MoMail API keys follow this format:

mk_{prefix}_{secret}

• mk_ — Fixed prefix identifying MoMail keys
• {prefix} — 8-character identifier shown in the dashboard
• {secret} — 24-character secret (only shown once)

Example: mk_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6

Using API Keys

cURL

curl -X GET https://api.momail.io/v1/domains \
  -H "X-API-Key: mk_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6"

JavaScript

const response = await fetch('https://api.momail.io/v1/domains', {
  headers: {
    'X-API-Key': 'mk_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6'
  }
});

Python

import requests

response = requests.get(
    'https://api.momail.io/v1/domains',
    headers={'X-API-Key': 'mk_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6'}
)

Security Best Practices

1. Never expose API keys in client-side code — Use environment variables or secure key management
2. Rotate keys regularly — Set expiration dates and create new keys periodically
3. Use separate keys for different environments — Create distinct keys for development, staging, and production
4. Revoke unused keys — Delete keys that are no longer needed

Revoking an API Key

To revoke an API key:

1. Go to Settings > API Keys in your dashboard
2. Find the key you want to revoke
3. Click Delete
4. Confirm the deletion

Once revoked, the key will immediately stop working and cannot be restored.

Authentication Errors

If your API key is missing, invalid, or expired, you will receive a 401 Unauthorized response:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

See Error Codes for a complete list of authentication errors.