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
/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
/v1/inboxes/check?address=agent@botmail.work
Instantly check whether a custom inbox address prefix or full address is available or already reserved/taken.
/v1/inboxes
List all active project inboxes in your workspace.
/v1/inboxes
Provision a new persistent or temporary inbox.
Messages, Archival & Storage Cleanup
/v1/messages?folder=inbox
List messages in your active inbox storage or folder=archive for reference storage.
/v1/messages/:id/archive
Move an email message to your metered Archive Box to free up active inbox storage.
/v1/messages/:id/trash
Permanently delete an unneeded message to free up quota.
/v1/messages
Send an outbound message from an inbox (internal deliveries bypass external mail relay with 0 credit consumption).
