Authentication - MailBreeze

API Keys

All API requests require authentication via an API key. You can create and manage keys in your dashboard.

Key Types

Key Prefix	Environment	Description
`sk_live_`	Production	Sends real emails, uses credits
`sk_test_`	Sandbox	Simulates sending, no emails delivered

Using a Key over SMTP

The same keys authenticate SMTP connections — there is no separate SMTP credential. Use apikey as the username and the key as the password. See Sending over SMTP.

Authenticating Requests

Include your API key in the x-api-key header:

curl -X POST https://api.mailbreeze.com/v1/emails \
  -H "x-api-key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Or with SDKs:

import { MailBreeze } from "mailbreeze";

const mailbreeze = new MailBreeze({ apiKey: "sk_live_xxx" });

from mailbreeze import MailBreeze

client = MailBreeze(api_key="sk_live_xxx")

import mailbreeze "github.com/MailBreeze/mailbreeze-go"

client := mailbreeze.NewClient("sk_live_xxx")

use MailBreeze\MailBreeze;

$mailbreeze = new MailBreeze('sk_live_xxx');

use mailbreeze::Client;

let client = Client::new("sk_live_xxx");

Key Permissions

API keys have full access to all endpoints for your domain. To restrict access:

Create separate keys for different applications
Revoke unused keys immediately
Rotate keys periodically

Security Best Practices

Never expose your API key in client-side code, public repositories, or logs.

Do

Store keys in environment variables
Use secret management systems (e.g., AWS Secrets Manager, Vault)
Rotate keys after team member departures
Use test keys for development

Don’t

Commit keys to version control
Share keys via email or chat
Use production keys in CI/CD logs
Hardcode keys in source code

Environment Variables

Store your API key in an environment variable:

MAILBREEZE_API_KEY=sk_live_xxx

const mailbreeze = new MailBreeze({
  apiKey: process.env.MAILBREEZE_API_KEY,
});

import os
from mailbreeze import MailBreeze

client = MailBreeze(api_key=os.environ["MAILBREEZE_API_KEY"])

client := mailbreeze.NewClient(os.Getenv("MAILBREEZE_API_KEY"))

Error Responses

Authentication errors return a 401 Unauthorized status:

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

Error Code	Description
`UNAUTHORIZED`	Missing or invalid API key
`KEY_REVOKED`	API key has been revoked
`KEY_EXPIRED`	API key has expired

Rate Limits

API requests are rate limited to 100 requests per minute per API key. Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 2024-01-01T12:01:00Z

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per minute
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	ISO timestamp when the limit resets

When exceeded, you’ll receive a 429 Too Many Requests response with a Retry-After header indicating seconds until reset.

​API Keys

​Key Types

​Using a Key over SMTP

​Authenticating Requests

​Key Permissions

​Security Best Practices

​Do

​Don’t

​Environment Variables

​Error Responses

​Rate Limits

API Keys

Key Types

Using a Key over SMTP

Authenticating Requests

Key Permissions

Security Best Practices

Do

Don’t

Environment Variables

Error Responses

Rate Limits