Cleanbox
Features Helpdesk Blog Pricing Contact
Sign in Start free trial
API Reference

Build with the Cleanbox API.

Manage aliases, contacts, messages, filters, domains, relay, and mailboxes programmatically. Bearer token authentication, JSON responses.

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer cb_your_api_key_here

API keys are team-scoped and managed from the Developer page in the dashboard. Only team owners can enable API access.

Documentation

GET /api/doc Get API documentation (no authentication required)
Response
{ "success": true, "documentation": { ... } }

Team

GET /api/team Get team info, usage, and limits
Response
{
    "success": true,
    "team": {
        "uuid": "a1b2c3d4-...",
        "name": "My Team",
        "plan": "Pro"
    },
    "usage": {
        "weekly_used": 42,
        "weekly_limit": 500
    },
    "limits": {
        "aliases": { "used": 12, "limit": 50 },
        "mailboxes": { "used": 2, "limit": 5 },
        "domains": { "used": 1, "limit": 3 },
        "filters": { "used": 4, "limit": 10 }
    }
}
GET /api/team/subscription Get subscription details including plan, pricing, and specifications
Response
{
    "success": true,
    "subscription": {
        "plan": "Pro",
        "price_monthly": "9.00",
        "price_yearly": "90.00",
        "trial_ends_at": null,
        "specifications": {
            "messages": 500,
            "mailboxes": 5,
            "aliases": 50,
            "domains": 3,
            "filters": 10,
            "cloud": 1,
            "relay": 1,
            "relay_accounts": 5
        }
    }
}

Addresses

GET /api/addresses List all addresses (aliases and relay)
Query parameters
page Page number (default: 1)
per_page Results per page (default: 25, max: 100)
type Filter by type: alias or relay
Response
{
    "success": true,
    "data": [
        {
            "uuid": "a1b2c3d4-...",
            "address": "myalias@cleanbox.me",
            "label": "Newsletters",
            "type": "alias",
            "active": true,
            "mailbox": "user@gmail.com",
            "spam_threshold": 5.0,
            "quarantine_threshold": null,
            "created_at": "2026-03-01T12:00:00+00:00"
        }
    ],
    "page": 1,
    "total_pages": 3
}
GET /api/addresses/{uuid} Get a single address (alias or relay)
Response
{
    "success": true,
    "address": {
        "uuid": "a1b2c3d4-...",
        "address": "myalias@cleanbox.me",
        "label": "Newsletters",
        "type": "alias",
        "active": true,
        "mailbox": "user@gmail.com",
        "spam_threshold": 5.0,
        "quarantine_threshold": null,
        "created_at": "2026-03-01T12:00:00+00:00"
    }
}
PUT /api/addresses/{uuid} Update an address
Body parameters
label Label or note (string or null)
spam_threshold Spam score threshold (float or null)
quarantine_threshold Quarantine score threshold (float or null)
Request
{ "label": "Shopping", "spam_threshold": 5.0 }
Response
{ "success": true }
PATCH /api/addresses/{uuid} Toggle address active state
Response
{ "success": true, "active": false }
DELETE /api/addresses/{uuid} Delete an address (alias only, relay addresses are blocked)
Response
{ "success": true }

Aliases

POST /api/aliases Create a new alias
Body parameters
name required Local part of the alias. Min 8 chars for cleanbox.me, min 2 for custom domains.
mailbox required UUID of the target mailbox
domain Custom domain name. Omit for cleanbox.me.
label Optional label or note
Request
{ "name": "myalias", "mailbox": "a1b2c3d4-...", "label": "Newsletters" }
Response
{
    "success": true,
    "alias": {
        "uuid": "a1b2c3d4-...",
        "address": "myalias@cleanbox.me",
        "label": "Newsletters",
        "active": true,
        "mailbox": "user@gmail.com"
    }
}
POST /api/aliases/random Create alias with random name
Body parameters
mailbox required UUID of the target mailbox
label Optional label or note
Request
{ "mailbox": "a1b2c3d4-..." }
Response
{
    "success": true,
    "alias": {
        "uuid": "a1b2c3d4-...",
        "address": "k7x2m9p4qr@cleanbox.me",
        "label": null,
        "active": true,
        "mailbox": "user@gmail.com"
    }
}

Contacts

GET /api/contacts List contacts
Query parameters
page Page number (default: 1)
per_page Results per page (default: 25, max: 100)
state Filter by state: unset, whitelisted, prioritized, muted, blocked
q Search by name or email
sort Sort by: name, emailCount, lastSeenAt, state
dir Sort direction: asc or desc
Response
{
    "success": true,
    "data": [
        {
            "uuid": "c1d2e3f4-...",
            "email": "sender@example.com",
            "name": "John Doe",
            "state": "whitelisted",
            "category": { "id": 3, "name": "Work", "icon": "briefcase" },
            "email_count": 42,
            "last_seen_at": "2026-03-01T12:00:00+00:00",
            "created_at": "2026-01-15T08:00:00+00:00"
        }
    ],
    "page": 1,
    "total_pages": 5
}
GET /api/contacts/{uuid} Get a single contact
Response
{
    "success": true,
    "contact": {
        "uuid": "c1d2e3f4-...",
        "email": "sender@example.com",
        "name": "John Doe",
        "state": "whitelisted",
        "category": { "id": 3, "name": "Work", "icon": "briefcase" },
        "email_count": 42,
        "last_seen_at": "2026-03-01T12:00:00+00:00",
        "created_at": "2026-01-15T08:00:00+00:00"
    }
}
PUT /api/contacts/{uuid} Update contact state and/or category
Body parameters
state One of: unset, whitelisted, prioritized, muted, blocked
category_id Category ID (int or null to remove)
Request
{ "state": "blocked", "category_id": 3 }
Response
{
    "success": true,
    "state": "blocked",
    "category_id": 3,
    "category_name": "Work",
    "category_icon": "briefcase"
}
GET /api/categories List all categories
Response
{
    "success": true,
    "data": [
        { "id": 1, "name": "Personal", "icon": "user" },
        { "id": 2, "name": "Shopping", "icon": "cart" },
        { "id": 3, "name": "Work", "icon": "briefcase" }
    ]
}

Relay

GET /api/relay List all relay domains with their protected addresses
Response
{
    "success": true,
    "data": [
        {
            "domain": "example.com",
            "domain_uuid": "d1e2f3a4-...",
            "relay_uuid": "r1e2l3a4-...",
            "addresses": [
                {
                    "uuid": "a1b2c3d4-...",
                    "address": "john@example.com",
                    "label": null,
                    "active": true,
                    "spam_threshold": 5.0,
                    "quarantine_threshold": null
                }
            ]
        }
    ]
}
GET /api/relay/{domain} Get relay details for a specific domain
Response
{
    "success": true,
    "domain": "example.com",
    "domain_uuid": "d1e2f3a4-...",
    "relay_uuid": "r1e2l3a4-...",
    "addresses": [
        {
            "uuid": "a1b2c3d4-...",
            "address": "john@example.com",
            "label": null,
            "active": true,
            "spam_threshold": 5.0,
            "quarantine_threshold": null
        }
    ]
}

Mailboxes

GET /api/mailboxes List all mailboxes
Response
{
    "success": true,
    "data": [
        {
            "uuid": "m1a2i3l4-...",
            "name": "Personal",
            "type": "imap",
            "address": "user@gmail.com",
            "active": true
        }
    ]
}
PATCH /api/mailboxes/{uuid}/toggle Toggle mailbox active state
Response
{ "success": true, "active": false }

Messages

GET /api/messages List messages
Query parameters
page Page number (default: 1)
per_page Results per page (default: 25, max: 100)
address Filter by address UUID (alias or relay)
contact Filter by contact UUID
status Filter by status: delivered, denied, rejected, failed, quarantined, bounced
q Search subject, sender, or alias address
Response
{
    "success": true,
    "data": [
        {
            "uuid": "m1n2o3p4-...",
            "from_address": "sender@example.com",
            "from_name": "John Doe",
            "subject": "Hello!",
            "status": "delivered",
            "alias": "myalias@cleanbox.me",
            "spam_score": 2.5,
            "has_attachments": false,
            "received_at": "2026-03-01T12:00:00+00:00"
        }
    ],
    "page": 1,
    "total_pages": 12
}
GET /api/messages/{uuid} Get message details
Response
{
    "success": true,
    "message": {
        "uuid": "m1n2o3p4-...",
        "from_address": "sender@example.com",
        "from_name": "John Doe",
        "subject": "Hello!",
        "status": "delivered",
        "alias": "myalias@cleanbox.me",
        "spam_score": 2.5,
        "size": 15234,
        "has_attachments": false,
        "properties": ["DKIM", "NEWSLETTER"],
        "feedback": null,
        "received_at": "2026-03-01T12:00:00+00:00"
    }
}
GET /api/messages/{uuid}/raw Download raw message (RFC 822)

Returns the raw RFC 822 message as a downloadable .eml file. Only available within the message retention window.

Response
Content-Type: message/rfc822
GET /api/messages/{uuid}/view Get rendered HTML and plain text

Returns the message body as base64-encoded HTML and plain text. Only available within the message retention window.

Response
{
    "success": true,
    "html": "PGh0bWw+Li4uPC9odG1sPg==",
    "text": "Hello, this is the plain text body..."
}
GET /api/messages/{uuid}/spamreport Get spam score and report
Response
{
    "success": true,
    "spam_score": 2.5,
    "rules": [
        {
            "rule": "DKIM_SIGNED",
            "score": -0.1,
            "description": "Message has a DKIM signature"
        }
    ]
}
GET /api/messages/{uuid}/attachments Get message attachments

Returns all attachments with base64-encoded content. Only available within the message retention window.

Response
{
    "success": true,
    "attachments": [
        {
            "filename": "document.pdf",
            "content_type": "application/pdf",
            "size": 245120,
            "content": "JVBERi0xLjQK..."
        }
    ]
}
GET /api/messages/{uuid}/attachment/{index} Download a single attachment (index starts at 1)

Returns the attachment as a downloadable file with the appropriate content type.

Response
Content-Type: application/pdf

Domains

GET /api/domains List all custom domains
Response
{
    "success": true,
    "data": [
        {
            "uuid": "d1o2m3a4-...",
            "name": "mydomain.com",
            "verified": true,
            "active": true,
            "created_at": "2026-03-01T12:00:00+00:00"
        }
    ]
}
GET /api/domains/{uuid} Get domain details including verification token
Response
{
    "success": true,
    "domain": {
        "uuid": "d1o2m3a4-...",
        "name": "mydomain.com",
        "verified": true,
        "active": true,
        "spf": true,
        "verification_token": "abc123def456ghi789jkl012",
        "created_at": "2026-03-01T12:00:00+00:00"
    }
}

Filters

GET /api/filters List all filters with groups, rules, and options
Response
{
    "success": true,
    "data": [
        {
            "uuid": "f1i2l3t4-...",
            "name": "Block promos",
            "alias": "myalias@cleanbox.me",
            "logic": "any",
            "action": "deny",
            "active": true,
            "groups": [
                {
                    "logic": "all",
                    "rules": [
                        {
                            "component": "subject",
                            "type": "contains",
                            "value": "unsubscribe"
                        }
                    ]
                }
            ],
            "options": { "store_folder": "Junk" }
        }
    ]
}
GET /api/filters/{uuid} Get filter details
Response
{
    "success": true,
    "filter": {
        "uuid": "f1i2l3t4-...",
        "name": "Block promos",
        "alias": "myalias@cleanbox.me",
        "logic": "any",
        "action": "deny",
        "active": true,
        "groups": [
            {
                "logic": "all",
                "rules": [
                    {
                        "component": "subject",
                        "type": "contains",
                        "value": "unsubscribe"
                    }
                ]
            }
        ],
        "options": { "store_folder": "Junk" }
    }
}
PATCH /api/filters/{uuid}/toggle Toggle filter active state
Response
{ "success": true, "active": false }

Quarantine

GET /api/quarantine List quarantined messages
Query parameters
page Page number (default: 1)
per_page Results per page (default: 50, max: 100)
q Search by subject, sender, or alias
Response
{
    "success": true,
    "data": [
        {
            "uuid": "m1n2o3p4-...",
            "from_address": "sender@example.com",
            "from_name": "Spammy Corp",
            "subject": "You won a prize!",
            "alias": "myalias@cleanbox.me",
            "spam_score": 8.5,
            "received_at": "2026-03-01T12:00:00+00:00"
        }
    ],
    "page": 1,
    "total_pages": 2
}
POST /api/quarantine/accept Accept quarantined messages and deliver them
Body parameters
messages required Array of message UUIDs
Request
{ "messages": ["m1n2o3p4-...", "a5b6c7d8-..."] }
Response
{
    "success": true,
    "processed": ["m1n2o3p4-..."],
    "failed": ["a5b6c7d8-..."]
}
POST /api/quarantine/reject Reject quarantined messages
Body parameters
messages required Array of message UUIDs
Request
{ "messages": ["m1n2o3p4-...", "a5b6c7d8-..."] }
Response
{
    "success": true,
    "processed": ["m1n2o3p4-...", "a5b6c7d8-..."],
    "failed": []
}

Cloud

GET /api/cloud Get cloud storage overview with contacts and usage
Response
{
    "success": true,
    "storage": {
        "used": 52428800,
        "limit": 524288000
    },
    "data": [
        {
            "uuid": "c1d2e3f4-...",
            "email": "sender@example.com",
            "name": "John Doe",
            "file_count": 3,
            "total_size": 1048576
        }
    ]
}
GET /api/cloud/{contact_uuid} Get files for a specific contact
Response
{
    "success": true,
    "contact": {
        "uuid": "c1d2e3f4-...",
        "email": "sender@example.com",
        "name": "John Doe"
    },
    "files": [
        {
            "uuid": "f1l2e3s4-...",
            "filename": "invoice.pdf",
            "extension": "pdf",
            "size": 245120,
            "message_uuid": "m1n2o3p4-..."
        }
    ]
}
GET /api/cloud/file/{uuid} Download a file

Returns the file with the appropriate content type.

Response
Content-Type: application/pdf
DELETE /api/cloud/file/{uuid} Delete a file
Response
{ "success": true }

Errors

All error responses follow this format:

{
    "success": false,
    "error": {
        "message": "Description of what went wrong",
        "code": "error_code"
    }
}
400Bad request — invalid or missing parameters
401Unauthorized — missing or invalid API key
403Forbidden — insufficient permissions or limit reached
404Not found — resource does not exist
410Gone — message no longer available (retention expired)
429Too many requests — rate limit exceeded

Ready to integrate?

Enable API access from the Developer page in your Cleanbox dashboard. Available for team owners on all plans.

Get started
No credit card required · Cancel anytime