API Keys

API keys are used to authenticate programmatic access to the MoMail API. Each key is tied to your account and carries specific rate limits and permissions.

List API Keys

Retrieve all API keys for your account.

GET /api-keys

Response

{
  "success": true,
  "data": [
    {
      "keyId": "key_abc123",
      "name": "Production API",
      "keyPrefix": "mk_a1b****",
      "plan": "pro",
      "rateLimit": 100,
      "lastUsed": "2024-01-15T10:30:00.000Z",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "expirationTs": null
    }
  ],
  "meta": {
    "total": 1
  }
}

Response Fields

Field	Type	Description
keyId	string	Unique identifier for the key
name	string	Human-readable name for the key
keyPrefix	string	Masked prefix of the API key
plan	string	Subscription plan (free, pro, enterprise)
rateLimit	number	Requests per minute allowed
lastUsed	string	ISO 8601 timestamp of last API call
createdAt	string	ISO 8601 timestamp of key creation
expirationTs	string	Expiration timestamp (null if no expiration)

Create API Key

Generate a new API key.

POST /api-keys

Request Body

{
  "name": "Production API",
  "expirationDays": 365
}

Parameters

Field	Type	Required	Description
name	string	Yes	Descriptive name (1-100 characters)
expirationDays	number	No	Days until key expires (1-365)

Response

{
  "success": true,
  "data": {
    "keyId": "key_abc123",
    "name": "Production API",
    "apiKey": "mk_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
    "keyPrefix": "mk_a1b****",
    "plan": "free",
    "rateLimit": 20,
    "expirationTs": "2025-01-15T00:00:00.000Z",
    "createdAt": "2024-01-15T10:30:00.000Z"
  },
  "meta": {
    "warning": "This API key will only be shown once. Please store it securely."
  }
}

Caution

The full apiKey is only returned once during creation. Store it securely, as it cannot be retrieved later.

Delete API Key

Revoke an API key.

DELETE /api-keys/{id}

Parameters

Parameter	Type	Required	Description
id	string	Yes	Key UUID

Response

{
  "success": true,
  "data": {
    "keyId": "key_abc123",
    "revoked": true
  }
}

Caution

Deleted keys are immediately invalidated and cannot be restored. Any applications using this key will stop working.

API Key Security

Best Practices

1. Use environment variables: Never hardcode API keys in source code
2. Rotate regularly: Set expiration dates and create new keys periodically
3. Use separate keys per environment: Create distinct keys for dev, staging, and production
4. Restrict access: Only grant necessary permissions per key

Environment Variable Example

# .env file
MOMAIL_API_KEY=mk_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

const apiKey = process.env.MOMAIL_API_KEY;

Code Examples

cURL

# List API keys
curl https://api.momail.io/v1/api-keys \
  -H "X-API-Key: your_key"

# Create API key
curl -X POST https://api.momail.io/v1/api-keys \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API",
    "expirationDays": 365
  }'

# Delete API key
curl -X DELETE https://api.momail.io/v1/api-keys/key_abc123 \
  -H "X-API-Key: your_key"

JavaScript

// List API keys
const keys = await fetch('https://api.momail.io/v1/api-keys', {
  headers: { 'X-API-Key': 'your_key' }
}).then(r => r.json());

// Create API key
const newKey = await fetch('https://api.momail.io/v1/api-keys', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Production API',
    expirationDays: 365
  })
}).then(r => r.json());

// IMPORTANT: Save the key immediately
const apiKey = newKey.data.apiKey;
localStorage.setItem('momail_api_key', apiKey);

// Delete API key
await fetch('https://api.momail.io/v1/api-keys/key_abc123', {
  method: 'DELETE',
  headers: { 'X-API-Key': 'your_key' }
});

Python

import os
import requests

headers = {'X-API-Key': os.getenv('MOMAIL_API_KEY')}

# List API keys
response = requests.get('https://api.momail.io/v1/api-keys', headers=headers)
keys = response.json()['data']

# Create API key
response = requests.post(
    'https://api.momail.io/v1/api-keys',
    headers=headers,
    json={
        'name': 'Production API',
        'expirationDays': 365
    }
)
result = response.json()

# IMPORTANT: Save the key immediately
api_key = result['data']['apiKey']
print(f"Save this key: {api_key}")

# Delete API key
requests.delete(
    'https://api.momail.io/v1/api-keys/key_abc123',
    headers=headers
)