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:8083/api/v1/

Replace your-server with your actual hostname or IP address. Port 8083 is the default host port mapping in docker-compose.yml (the container listens on 8080); production deployments typically front this with a reverse proxy on 443.

Authentication¶

Most requests authenticate with an API key; browser dashboards use session cookies instead:

Platform-only endpoints (service restarts, cross-tenant listings, and similar) require a platform-scoped credential; many additionally require an operator role and so can only be reached by an operator session.

See the Authentication page for all four credential types, CSRF rules, and the bootstrap flow that issues your first key.

Request & Response Format¶

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

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

{
  "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¶

The HTTP API does not enforce a blanket requests-per-hour quota on valid credentials. What is enforced:

All of these return 429 Too Many Requests when tripped.

Email sending rate limits (messages per hour/day/month for organizations, domains, mailboxes, and individual SMTP credentials) are a separate system — see Rate Limiting.

HTTP Status Codes¶

See the Errors page for the full error reference.

Available Endpoints¶

The full endpoint index lists all 307 endpoints across the 32 route modules. You can also browse the live Swagger UI or Redoc reference on your own deployment.

Quick Start¶

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

# 1. Check the server is running (no auth required)
curl http://your-server:8083/health

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

# 3. Create a domain (tenant keys create it in their own org automatically)
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}' \
  http://your-server:8083/api/v1/domains/

# 4. Create a mailbox (passwords: 12+ chars with letters and numbers)
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com", "password": "secure-pass-1234", "name": "Alice"}' \
  http://your-server:8083/api/v1/mailboxes/email-accounts

import requests

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

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

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

# Create a mailbox
mailbox = requests.post(
    f"{BASE}/mailboxes/email-accounts",
    headers=HEADERS,
    json={"email": "alice@example.com", "password": "secure-pass-1234", "name": "Alice"},
)
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