API keys and developer access

The Cleanbox REST API gives you programmatic access to your team's aliases, contacts, messages, filters, domains, relay, cloud storage, and quarantine. This article explains how to enable API access, authenticate, and get started with your first request.

Enabling the API

1. Go to Developer in the sidebar
2. Toggle Enable API access

When you enable the API, it becomes active for your entire team. All team members share the same API token. Only the team owner can enable or disable API access.

Your API key

After enabling the API, your key is displayed in a masked format (first 8 characters visible). You can:

• Show token — Reveals the full API key. Keep this secret — anyone with the key has access to your team's data.
• Regenerate — Creates a new API key and invalidates the old one immediately. Use this if your key is compromised.

Base URL and authentication

All API requests use the base URL:

https://api.cleanbox.app/v1

Every request requires a Bearer token in the Authorization header:

Authorization: Bearer your_api_key_here

Rate limiting

The API is rate-limited to prevent abuse. Rate limit information is included in every response via headers:

Header	Description
X-RateLimit-Limit	Maximum requests allowed per window
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Seconds until the rate limit resets

If you exceed the limit, the API returns a 429 Too Many Requests error. Wait for the reset window before retrying.

Available resources

The API provides access to all core Cleanbox features:

Resource	Endpoints	What you can do
Team	GET	Get team info, usage stats, limits, and subscription details
Addresses	GET, PUT, PATCH, DELETE	List, update, toggle, and delete aliases and relay addresses
Aliases	POST	Create new aliases (named or random)
Contacts	GET, PUT	List, search, update state and category
Messages	GET	List, search, view details, download raw email, get spam reports and attachments
Quarantine	GET, POST	List quarantined messages, bulk accept or reject
Domains	GET	List domains and get verification details
Filters	GET, PATCH	List filters with rules, toggle active state
Relay	GET	List relay domains and protected addresses
Mailboxes	GET, PATCH	List mailboxes, toggle active state
Cloud	GET, DELETE	Browse files by contact, download or delete
Categories	GET	List all 20 contact categories

Example: creating a new alias

Here is a complete example of creating a new alias using curl:

curl -X POST https://api.cleanbox.app/v1/aliases 
  -H "Authorization: Bearer your_api_key_here" 
  -H "Content-Type: application/json" 
  -d '{"name": "shopping", "mailbox": "a1b2c3d4-...", "label": "Online shops"}'

Response:

{
    "success": true,
    "alias": {
        "uuid": "e5f6g7h8-...",
        "address": "shopping@cleanbox.me",
        "label": "Online shops",
        "active": true,
        "mailbox": "user@gmail.com"
    }
}

To create a random alias instead:

curl -X POST https://api.cleanbox.app/v1/aliases/random 
  -H "Authorization: Bearer your_api_key_here" 
  -H "Content-Type: application/json" 
  -d '{"mailbox": "a1b2c3d4-..."}'

Example: blocking a contact

curl -X PUT https://api.cleanbox.app/v1/contacts/c1d2e3f4-... 
  -H "Authorization: Bearer your_api_key_here" 
  -H "Content-Type: application/json" 
  -d '{"state": "blocked"}'

Error handling

All errors return a consistent JSON format:

{
    "success": false,
    "error": {
        "message": "Description of what went wrong",
        "code": "error_code"
    }
}

Code	Meaning
400	Bad request — invalid or missing parameters
401	Unauthorized — missing or invalid API key
403	Forbidden — insufficient permissions or limit reached
404	Not found — resource does not exist
410	Gone — message content no longer available (retention expired)
429	Too many requests — rate limit exceeded

Access restrictions

• API access is available to the team owner only
• The API key is team-scoped — it accesses all resources within the team
• Regenerating the key invalidates the old key immediately
• API actions are not currently logged in the activity log

Full API reference

For the complete endpoint documentation with all parameters, request/response examples, and detailed descriptions, see the API Reference on our website.