Manual for AI bots — x402 Bot Mailbox Server

You are a software agent (CLI, cron job, or LLM tool) calling this host over HTTPS. Paid routes use x402: the first request may return 402 Payment Required; settle USDC on Base, send the proof (for example `X-PAYMENT`), and retry the same operation. Read live prices from `GET /admin-api/ui/config` (JSON).

Base URL

Append paths below to `https://mail.cusethejuice.com/admin-api` (no trailing slash). On the live manual page the server substitutes your host’s `/admin-api` base (for example https://your-mail-host.example/admin-api).

Authentication

Mailbox APIs

• JSON body: email, username (mailbox login name; same value as create-user field linux_user), password.
• Query or headers: username, password; headers `X-CTJ-Username` / `X-CTJ-Password` are accepted on many routes.
• Optional TOTP MFA: when enabled on the mailbox, also send `mfa_code`, `mfa`, or `otp` in JSON/form, or header `X-CTJ-MFA` (six digits). Enroll with `POST /machine/request/mailbox/mfa-enroll` (password only), confirm with `POST /machine/request/mailbox/mfa-confirm` (secret + mfa_code), disable with `POST /machine/request/mailbox/mfa-disable`.

Domain administrator

• Custom-domain flows use the domain administrator password (not a mailbox password).
• Sign-in: `POST /ui/domain-admin/login/start` with domain, admin_password, optional mfa_code when login MFA is enabled for that domain.
• Forgot admin password: x402 fee per attempt (default $1.00 USDC, X402_DOMAIN_ADMIN_FORGOT_PASSWORD_PRICE_USDC) — recovery PIN (4–12 digits from registration) or one-time email code to the external recovery address on file — use the Domain admin HTML flows or `scripts/python-pay-ui-domain-admin-forgot-pin.py` / `scripts/python-pay-ui-domain-admin-forgot-email.py` (CDP/Agentic GET pay URLs: /admin-api/ui/domain-admin/pay/forgot-pin and /admin-api/ui/domain-admin/pay/forgot-email).

Create user / custom domains

• The default hosted domain on this server may allow Create user without a domain-admin password; other hosted domains and registered custom domains require `domain_admin_password` on `POST /users/add` and the Create user form.
• Register domain (BYOD): annual x402 on `/ui/custom-domain/register`; Domain admin panel lists MX / SPF / DKIM / DMARC hints.

Discover prices

• `GET /ui/config` — per-action USDC amounts, facilitator fields, OWS hints.
• Cache briefly; amounts may change when the operator updates policy.

Mailbox JSON routes (prefer POST /machine/request/* or canonical /machine/mailboxes/...)

Operation	Method	Path	Notes
List messages	GET	/machine/mailboxes/{email}/messages	Query auth; optional limit
List messages	POST	/machine/mailboxes/{email}/messages or /machine/request/list	JSON credentials
Search	POST	/machine/mailboxes/{email}/search or /machine/request/search	query or q; optional folder, limit, max_scan
Get message	GET/POST	/machine/mailboxes/{email}/messages/{message_id} or /machine/request/message
Attachments	GET/POST	.../attachments or /machine/request/attachments
Quota	GET/POST	/machine/mailboxes/{email}/quota or /machine/request/quota
Send	POST	/machine/request/send	to, subject, body; optional cc/bcc
Move / delete / forward / reply / reply-all	POST	/machine/request/move …	message_id + operation fields
Folders	POST	/machine/request/folder/create …	Not INBOX, x402.Pending, x402.Spam
Reset password	POST	/machine/request/mailbox/reset-password	current + new_password
Download zip	POST	/machine/request/mailbox/download	returns download_url, TTL, max uses
Recovery email	POST	/machine/request/mailbox/recovery-email	external domain only
MFA enroll / confirm / disable	POST	/machine/request/mailbox/mfa-enroll …	see Authentication
Account recovery request	POST	/machine/request/account-recovery/request	no mailbox password
Account recovery complete	POST	/machine/request/account-recovery/complete	recovery_code, new_password
Trust index	POST	/machine/request/trust/list …	if enabled on host

Account deletion is not available over HTTP. Contact the operator if a mailbox must be removed.

Account creation

• Machine: `POST /users/add` with domain, localpart, linux_user, password (+ x402 after 402).
• Human / probe: `GET`/`HEAD /users/add` with query params; HTML 402.

Human HTML + x402 (session cookies)

• `/machine/human/...` — compose → paid GET → POST with password (and `mfa_code` when MFA enabled). Use `/machine/request/*` for headless agents when possible.
• Storage upgrade: `POST /ui/storage-upgrade/start` → `/ui/storage-upgrade/pay/{tier}`.
• Domain admin login pay: `POST /ui/domain-admin/login/start` → `/ui/domain-admin/pay/login` → `POST /ui/domain-admin/login/complete`.

OpenClaw + MoonPay OWS

• Use `ows pay request` for priced routes; see `/admin-api/ui/openclaw` on this host and the companion x402_mailbox_ows skill.
• The public x402 pay-to address for this integration is fixed in that documentation; the OWS wallet UUID is the signer, not the pay-to address.

Agent behavior

• Prefer POST JSON under `/machine/request/` or canonical `/machine/mailboxes/` paths.
• On 402, settle x402 and retry; do not assume idempotency across unrelated payments.
• On 429, back off (rate limits).
• Never log passwords or MFA codes; use HTTPS only.

Related docs

• `/admin-api/ui/manual-humans` — people using IMAP, web forms, domain admin.
• `/admin-api/ui/openclaw` — OWS integration summary on this host.