API Reference

The 3AVA Mail API is REST over HTTPS, with JSON request and response bodies.

Base URL

https://mail.3ava.com/api

For self-hosted installations: whatever EMAILAPI_BASE_URL you configured.

Authentication

Every authenticated request carries a bearer token:

Authorization: Bearer am_YOUR_KEY

See Authentication for details on permissions and scoping.

Content type

Requests and responses use application/json unless specified otherwise. Multipart uploads (CSV imports) use multipart/form-data.

Resource IDs

All IDs are UUIDv4 strings:

e04570c0-c0f7-4c75-8fd1-be90476b17a3

Response shape

Successful responses return the resource directly, not wrapped in an envelope:

{
  "id": "...",
  "created_at": "2026-04-22T22:30:00Z",
  ...
}

Errors return:

{
  "detail": "Domain not verified"
}

with the appropriate HTTP status code. See Errors.

Pagination

List endpoints accept limit (default varies, max 100) and offset (default 0) query parameters. Total counts are returned in the X-Total-Count response header where available.

Versioning

The API is currently unversioned (v1 is implicit). Breaking changes will be announced via webhook (account.api_change) at least 30 days before they ship and will introduce a new path prefix (/v2/...) — /v1/ paths will continue to work for at least 12 months after.

Rate limits

Default: 50 requests/sec per account on POST /emails. See Rate limits.

Conventions

• Timestamps are ISO 8601 in UTC.
• Email addresses are normalized to lowercase before storage.
• Phone numbers are normalized to E.164 (US default if no country code).
• Empty strings are coerced to null for nullable fields.