API Documentation

This document covers the current authenticated Developer API implemented under /api.

It documents only the public API surface that exists in code today:

• account
• subscription
• usage
• domains
• mailboxes
• emails
• attachment download URLs

• Base path: /api
• Authentication: Authorization: Bearer <api_key>
• Current supported API version: 2026-04-23
• Access: available only to users whose plan has Developer API access
• Developer app and API key management: handled in the dashboard UI, not through public API endpoints

• Authorization: Bearer <api_key> is required on all Developer API endpoints
• Zemail-Version: 2026-04-23 is optional

If Zemail-Version is omitted, the API resolves to the app default version for the key, then falls back to the platform default.

• Zemail-Version
• Zemail-Request-Id

Zemail-Request-Id is also echoed inside error payloads.

The Developer API is account-scoped:

• requests run as the user who owns the API key
• rate limits are enforced at the user/account level, not per key
• mailbox and email access is limited to resources owned by that user

• account:read
• subscription:read
• usage:read
• domains:read
• mailboxes:read
• mailboxes:create
• mailboxes:delete
• emails:read
• emails:delete
• emails:mark-read

• apps limit: 3
• keys limit: 10
• requests per minute: 120
• requests per day: 25000
• mailboxes page size max: 100
• emails page size max: 50
• request log retention: 7 days

• apps limit: 10
• keys limit: 30
• requests per minute: 600
• requests per day: 150000
• mailboxes page size max: 100
• emails page size max: 100
• request log retention: 30 days

{
  "object": "mailbox",
  "data": {},
  "meta": {}
}

{
  "object": "list",
  "data": [],
  "has_more": false,
  "next_cursor": null,
  "meta": {}
}

List endpoints use Laravel page pagination. Pass ?page= to move forward. next_cursor is currently the next page number when another page exists.

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "A Zemail API key must be provided via the Authorization Bearer header.",
    "param": null,
    "request_id": "zreq_example"
  }
}

Validation errors add an errors object keyed by field name.

Required scope: account:read

Returns the authenticated account snapshot.

Response fields

• id
• name
• email
• email_verified_at
• tier
• tier_label
• current_plan
• developer_api

Example response

Example abbreviated for readability:

{
  "object": "account",
  "data": {
    "id": 1,
    "name": "Jane Doe",
    "email": "[email protected]",
    "email_verified_at": "2026-04-20T12:00:00+00:00",
    "tier": "plus",
    "tier_label": "PLUS",
    "current_plan": {
      "slug": "plus",
      "name": "Plus"
    },
    "developer_api": {
      "enabled": true,
      "default_version": "2026-04-23",
      "limits": {
        "apps_limit": 3,
        "keys_limit": 10,
        "requests_per_minute": 120,
        "requests_per_day": 25000,
        "mailboxes_page_size": 100,
        "emails_page_size": 50,
        "request_log_retention_days": 7
      }
    }
  },
  "meta": {}
}

Required scope: subscription:read

Returns the user’s current subscription snapshot.

Response fields

• status
• tier
• plan
• starts_at
• ends_at
• cancelled_at

Required scope: usage:read

Returns mailbox, storage, and Developer API usage details.

Response fields

• mailboxes.active_count
• mailboxes.active_limit
• mailboxes.daily_count
• mailboxes.daily_limit
• storage.limit_bytes
• storage.actual_used_bytes
• storage.visible_used_bytes
• storage.hidden_email_count
• storage.percent
• developer_api.apps_count
• developer_api.keys_count
• developer_api.limits

Required scope: domains:read

Returns active, non-archived domains accessible to the authenticated user.

Response item fields

• id
• name
• allowed_types

Required scope: mailboxes:read

Query parameters

• limit optional, default 25, capped by plan
• page optional

Returns the authenticated user’s non-blocked mailboxes ordered newest first.

Response item fields

• id
• address
• type
• domain
• expires_at
• created_at
• unread_count
• emails_count

List meta

• current_page
• per_page
• total

Required scope: mailboxes:create

Creates a mailbox for the authenticated user.

Request body

• type required, one of random or custom
• domain optional string
• username required when type=custom
• google_alias_mode optional, one of auto, dot, plus, combined

Current behavior

• type=random
  • creates a mailbox on an eligible public domain
  • if domain is provided, it must be an accessible active public domain
• type=custom
  • uses the provided domain
  • if the domain is one of the Google alias domains, the API may generate the final address from a Google username pool
  • otherwise the final address is <username>@<domain>

Mailbox creation notes

• custom usernames must be at least 6 characters
• custom usernames may contain letters, numbers, and single ., -, or + separators between alphanumeric segments
• if a previously deleted address owned by the same user exists, the API may restore it instead of creating a brand new record

Required scope: mailboxes:read

Returns a single owned mailbox using the same shape as mailbox list items.

Required scope: mailboxes:delete

Deletes an owned mailbox.

Response

{
  "object": "mailbox.deleted",
  "data": {
    "deleted": true,
    "id": 123
  },
  "meta": {}
}

Required scope: emails:read

Query parameters

• limit optional, default 25, capped by plan
• page optional
• search optional, matches subject, sender_email, and sender_name

Returns visible emails for an owned mailbox ordered newest first.

Response item fields

• id
• sender
• sender_email
• subject
• preview
• received_at
• is_read
• is_blocked
• attachments_count

Blocked sender domains are returned as blocked email summaries instead of normal message details.

Required scope: emails:read

Returns full details for an owned visible email.

Response fields

• id
• sender
• sender_name
• sender_email
• subject
• preview
• received_at
• is_read
• is_blocked
• blocked_domain
• body_text
• body_html
• attachments

Attachment fields

• id
• name
• size
• downloadable

If the email is blocked by mailbox policy:

• is_blocked is true
• blocked_domain is set
• body_html is null
• attachments is an empty array

Required scope: emails:delete

Deletes an owned email.

Response

{
  "object": "email.deleted",
  "data": {
    "deleted": true,
    "id": 456
  },
  "meta": {}
}

Required scope: emails:mark-read

Marks an owned email as read.

Response

{
  "object": "email",
  "data": {
    "id": 456,
    "is_read": true
  },
  "meta": {}
}

Required scope: emails:read

Creates a temporary download URL for an owned attachment.

Response fields

• url
• expires_at

This endpoint only works when the attachment exists and has a downloadable S3 key.

The following error codes are currently implemented in the Developer API surface:

• missing_api_key
• invalid_api_key
• api_key_revoked
• api_key_expired

• developer_api_not_enabled
• insufficient_scope

• unsupported_version
• rate_limit_exceeded
• daily_rate_limit_exceeded

• validation_failed
• domain_not_accessible
• daily_limit_reached
• mailbox_limit_reached
• mailbox_creation_failed
• address_in_use
• address_in_cooldown
• mailbox_delete_failed
• attachment_not_available

• mailbox_not_found
• email_not_found

The following are intentionally not part of the current public Developer API contract:

• API endpoints for creating or revoking developer apps
• API endpoints for creating or revoking API keys