API Reference¶

The Mailyte REST API is your control plane for managing organizations, domains, email accounts, aliases, webhooks, and everything else — all from code. If you can curl it, you can automate it.

In this section¶

Base URL¶

All API endpoints are served under:

http://your-server:5000/api/v1/

Replace your-server with your actual hostname or IP address.

Authentication¶

Every request must include one of two headers:

See the Authentication page for details on creating keys and permission levels.

Request & Response Format¶

{
  "type": "success",
  "msg": "Organizations retrieved successfully",
  "data": { ... }
}

{
  "type": "error",
  "msg": "Organization not found"
}

{
  "type": "error",
  "msg": "Validation failed",
  "data": {
    "errors": [
      "Organization name is required",
      "Invalid admin email format"
    ]
  }
}

Pagination¶

List endpoints support pagination with these query parameters:

Paginated responses include a pagination object:

{
  "type": "success",
  "msg": "Organizations retrieved successfully",
  "data": {
    "items": [ ... ],
    "pagination": {
      "page": 1,
      "per_page": 50,
      "total": 127,
      "total_pages": 3
    }
  }
}

Rate Limiting¶

API keys are rate-limited to 1,000 requests per hour by default. When you exceed the limit, the API returns 429 Too Many Requests.

HTTP Status Codes¶

See the Errors page for the full error reference.

Available Endpoints¶

Quick Start¶

The fastest way to verify your API is working and start exploring:

# 1. Check the server is running
curl http://your-server:5000/health

# 2. List your organizations
curl -H "X-API-Key: YOUR_KEY" \
  http://your-server:5000/api/v1/organizations

# 3. Create a domain
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "organization_id": "acme"}' \
  http://your-server:5000/api/v1/domains

# 4. Create a mailbox
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "domain": "example.com", "password": "secure-pass-123"}' \
  http://your-server:5000/api/v1/mailboxes

import requests

BASE = "http://your-server:5000/api/v1"
HEADERS = {"X-API-Key": "YOUR_KEY"}

# List organizations
orgs = requests.get(f"{BASE}/organizations", headers=HEADERS)
print(orgs.json())

# Create a domain
domain = requests.post(
    f"{BASE}/domains", headers=HEADERS, json={"domain": "example.com", "organization_id": "acme"}
)
print(domain.json())

# Create a mailbox
mailbox = requests.post(
    f"{BASE}/mailboxes",
    headers=HEADERS,
    json={"username": "alice", "domain": "example.com", "password": "secure-pass-123"},
)
print(mailbox.json())

Most common workflows¶

Related sections¶

• Getting Started -- install the server and send your first email
• Features -- understand what each feature does beyond the API
• Architecture -- how the API fits into the broader system
• Security -- authentication, authorization, and API key management