REST API Reference

The Botmail REST API is available at https://botmail-api.support8726.workers.dev/v1 (or your custom deployment domain). Authenticate requests using Bearer tokens (Supabase JWT or Agent credentials).

Account Usage & Quotas

GET/v1/usage

Retrieve workspace subscription tier, active status, and real-time usage metrics across inboxes, active inbox storage, archive box storage, and daily inbound/outbound volume.

{
  "tier": "solo",
  "status": "active",
  "usage": {
    "inboxes": { "used": 3, "limit": 10, "resetsAt": null },
    "messages": { "used": 42, "limit": 500, "resetsAt": null },
    "archive": { "used": 120, "limit": 2500, "resetsAt": null },
    "inbound": { "used": 14, "limit": 500, "resetsAt": "daily" },
    "outbound": { "used": 5, "limit": 200, "resetsAt": "daily" }
  }
}

Inboxes & Availability

GET/v1/inboxes/check?address=agent@botmail.work

Instantly check whether a custom inbox address prefix or full address is available or already reserved/taken.

GET/v1/inboxes

List all active project inboxes in your workspace.

POST/v1/inboxes

Provision a new persistent or temporary inbox.

Messages, Archival & Storage Cleanup

GET/v1/messages?folder=inbox

List messages in your active inbox storage or folder=archive for reference storage.

POST/v1/messages/:id/archive

Move an email message to your metered Archive Box to free up active inbox storage.

POST/v1/messages/:id/trash

Permanently delete an unneeded message to free up quota.

POST/v1/messages

Send an outbound message from an inbox (internal deliveries bypass external mail relay with 0 credit consumption).