API Overview

Base URL

All API send requests are made to:

https://api.emitlo.com/api/v1

Dashboard management endpoints (domains, credentials, webhooks, stats) are available at:

https://app.emitlo.com/api/v1

Note

In a single-server setup, both URLs point to the same server. In a split-server setup, api.emitlo.com is the dedicated Go API server for high-throughput sending.

---

Authentication

Emitlo uses Bearer token authentication. Include your credential secret key in every request:

Authorization: Bearer YOUR_API_KEY

Caution

Your API key grants access to your organization’s data. Never expose it in client-side code, public repositories, or logs. Use environment variables.

---

Permissions

Each credential has a set of permissions that control what it can do:

Permission	Description
send	Send emails via the API
stats	Read message status and statistics
admin	Manage domains, credentials, suppressions, and webhooks

A credential can have multiple permissions. For example, a backend service typically needs send + stats.

---

Response format

All responses use JSON with a consistent envelope:

{
  "status": "success",
  "data": { ... }
}

On error:

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The from_email field is required.",
    "details": {
      "from_email": ["The from_email field is required."]
    }
  }
}

---

HTTP status codes

Status	Meaning
200 OK	Request succeeded
201 Created	Resource created
202 Accepted	Message queued for delivery
401 Unauthorized	Invalid or missing API key
403 Forbidden	Insufficient permissions
404 Not Found	Resource not found
409 Conflict	Resource already exists
422 Unprocessable Entity	Validation error
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Server error

---

Error codes

Code	HTTP	Description
UNAUTHENTICATED	401	Invalid or missing credential
FORBIDDEN	403	Insufficient permissions for this action
NOT_FOUND	404	Resource not found
CONFLICT	409	Resource already exists (e.g. duplicate domain)
VALIDATION_ERROR	422	Request body failed validation
RATE_LIMITED	429	Send rate limit exceeded
ATTACHMENT_TOO_LARGE	422	Attachment exceeds plan size limit
MESSAGE_TOO_LARGE	422	Total message size exceeds platform limit
INTERNAL_ERROR	500	Unexpected server error

See Error Codes Reference for full details and handling examples.

---

Rate limiting

Requests are rate-limited per organization. When exceeded, the API returns 429 with a Retry-After header indicating when you can retry.

See Rate Limits for details.