milbox
Sign in

Documentation

One REST API, bearer key authentication, JSON in and out. Machine-readable spec lives at/openapi.json.

API v1.6.0llms.txtopenapi.json

Authenticate

Create a key in the panel, then send it as a bearer token. The secret is shown once at creation, so store it before you navigate away.

curl -s https://milbox.dev/api/v1/account \
  -H "authorization: Bearer $MILBOX_KEY"

Core endpoints

  • GET/api/v1/metaVersion, supported events, and capabilities
  • GET/api/v1/accountThe account behind the key, and its limits
  • GET/api/v1/plansCurrent plan plus the full catalogue
  • POST/api/v1/addressesCreate a mailbox on a domain
  • GET/api/v1/addressesList mailboxes owned by the key
  • GET/api/v1/inboxEvery message across the key, newest first
  • GET/api/v1/inbox/countsUnread and total counters per address
  • GET/api/v1/messages/:idOne message with parsed headers and bodies
  • POST/api/v1/messages/bulkRead, star, or delete many at once
  • POST/api/v1/webhooksSubscribe a URL to platform events

Full inventory, request bodies, and response shapes are on the panel under/developers/api once signed in.

Webhooks

Register a URL and the panel POSTs to it. Every request carriesx-milbox-signature, an HMAC-SHA256 oftimestamp.body keyed with the webhook secret. Verify it before trusting the payload.

message.receivedaddress.createdaddress.expiredmessage.deleted

Error codes

  • 401invalid_api_keyMissing, revoked, or expired key
  • 403insufficient_scopeKey scope does not cover this route
  • 403domain_not_publishedPool domain is not published by an operator
  • 404not_foundResource does not exist, or is not yours
  • 422validation_failedA body field is missing or malformed
  • 429rate_limitedPer-key budget exhausted; honour retry_after