Authentication

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

API Key Authentication

All /v1/api/* and /v1/mcp requests must send your API key as a Bearer token:

Authorization: Bearer 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://momail.io/v1/api/mailboxes \
  -H "Authorization: Bearer mk_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6"

JavaScript

const response = await fetch('https://momail.io/v1/api/mailboxes', {
  headers: {
    Authorization: 'Bearer mk_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6',
  },
});

Python

import requests

response = requests.get(
    'https://momail.io/v1/api/mailboxes',
    headers={'Authorization': 'Bearer mk_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6'},
)

MCP (Claude Desktop)

Use the same Bearer value in MCP server headers:

{
  "mcpServers": {
    "momail": {
      "transport": "streamableHttp",
      "url": "https://momail.io/v1/mcp",
      "headers": {
        "Authorization": "Bearer your_api_key"
      }
    }
  }
}

See Claude Desktop configuration.

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": "Authorization: Bearer <api-key> required"
  }
}

See Error Codes for a complete list of authentication errors.