{ "openapi": "3.1.0", "info": { "title": "AGNT Mail", "version": "1.0.0", "description": "Standalone Mail: Starter $5/month (1 inbox, 1000 units, 250 MB), Pro $15 (5 inboxes, 5000 units, 1 GB), Business $39 (15 inboxes, 20000 units, 3 GB). Monthly units and incoming storage pooled per account. No existing AGNT account required. Agents can fund headlessly with USDC on Base over x402." }, "servers": [ { "url": "https://mail.agnt.gg/mail/v1" } ], "components": { "securitySchemes": { "mailKey": { "type": "http", "scheme": "bearer", "description": "Secret from POST /agents or an owner-minted key (mail_…)." } }, "schemas": { "Inbox": { "type": "object", "properties": { "id": { "type": "string" }, "address": { "type": "string" }, "state": { "type": "string", "enum": [ "provisioning", "active" ] } } }, "Usage": { "type": "object", "properties": { "credit": { "type": "integer", "description": "microUSD" }, "reserved": { "type": "integer" }, "available": { "type": "integer" }, "frozen": { "type": "boolean" }, "hosting": { "type": "object", "properties": { "eligible": { "type": "boolean" }, "source": { "enum": [ "agnt_subscription", "standalone", "none" ] }, "remainingUnits": { "type": "integer" }, "usedUnits": { "type": "integer" }, "reservedUnits": { "type": "integer" }, "hostingUntil": { "type": "integer" }, "resetAt": { "type": "integer" }, "allowOverage": { "type": "boolean" }, "autoRenew": { "type": "boolean" }, "storageBytes": { "type": "integer" }, "storedBytes": { "type": "integer" } } } } } } }, "paths": { "/agents": { "post": { "summary": "Headless agent signup", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,39}$" } } } } } }, "responses": { "201": { "description": "Created. secret is shown once.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string" }, "secret": { "type": "string" }, "balance": { "type": "integer" }, "fund": { "type": "object", "properties": { "claimUrl": { "type": "string" }, "x402": { "type": "string" } } } } } } } }, "429": { "description": "Rate limited" } } } }, "/agents/{agentId}/claim": { "get": { "summary": "Funding status of an agent", "security": [], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "funded": { "type": "boolean" }, "available": { "type": "integer" } } } } } } } } }, "/usage": { "get": { "summary": "Balance", "security": [ { "mailKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } } } } }, "/inboxes": { "get": { "summary": "List inboxes", "security": [ { "mailKey": [] } ], "responses": { "200": { "description": "OK" } } }, "post": { "summary": "Create inbox (requires funded account)", "security": [ { "mailKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9-]{2,31}$" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inbox" } } } }, "402": { "description": "insufficient_credit" } } } }, "/inboxes/{id}/messages": { "get": { "summary": "List messages", "security": [ { "mailKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } }, "post": { "summary": "Send", "security": [ { "mailKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to", "subject", "text" ], "properties": { "to": { "type": "string", "format": "email" }, "subject": { "type": "string", "maxLength": 200 }, "text": { "type": "string" }, "html": { "type": "string", "maxLength": 100000 }, "attachments": { "type": "array", "maxItems": 10, "items": { "type": "object", "required": [ "filename", "content" ], "properties": { "filename": { "type": "string", "maxLength": 180 }, "contentType": { "type": "string" }, "content": { "type": "string", "contentEncoding": "base64" } } } } } } } } }, "responses": { "202": { "description": "Queued" }, "402": { "description": "insufficient_credit" }, "409": { "description": "idempotency_conflict" }, "429": { "description": "daily_sending_limit" } } } }, "/inboxes/{id}/messages/{messageId}": { "get": { "summary": "Read message", "security": [ { "mailKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/inboxes/{id}/messages/{messageId}/reply": { "post": { "summary": "Reply", "security": [ { "mailKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" }, "html": { "type": "string", "maxLength": 100000 }, "attachments": { "type": "array", "maxItems": 10, "items": { "type": "object", "required": [ "filename", "content" ], "properties": { "filename": { "type": "string", "maxLength": 180 }, "contentType": { "type": "string" }, "content": { "type": "string", "contentEncoding": "base64" } } } } } } } } }, "responses": { "202": { "description": "Queued" } } } }, "/deliveries/{deliveryId}": { "get": { "summary": "Delivery state", "security": [ { "mailKey": [] } ], "parameters": [ { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "queued", "submitting", "uncertain", "accepted_remote", "accepted_local", "rejected" ] } } } } } } } } }, "/plans": { "get": { "summary": "Published hosting policy", "security": [], "responses": { "200": { "description": "Current plan policy" } } } }, "/hosting/purchase": { "post": { "summary": "Activate or upgrade selected prepaid Mail plan", "security": [ { "mailKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 100 } } ], "responses": { "200": { "description": "Hosting period activated once" }, "402": { "description": "Insufficient prepaid credit" }, "403": { "description": "Owner or mail:manage required" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "enum": [ "starter", "pro", "business" ], "default": "starter" } } } } } } } }, "/hosting/preferences": { "put": { "summary": "Opt into balance renewal or prepaid overage", "security": [ { "mailKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "autoRenew", "allowOverage" ], "properties": { "autoRenew": { "type": "boolean" }, "allowOverage": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated hosting status" } } } }, "/agents/{agentId}/fund": { "post": { "summary": "Fund agent hosting from existing owner credit", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Hosting activated once" }, "402": { "description": "Insufficient owner credit" }, "403": { "description": "Owner credentials required" } } } }, "/webhooks": { "get": { "summary": "List notification endpoints; owner authentication required", "responses": { "200": { "description": "Endpoints without signing secrets" } } }, "post": { "summary": "Register a public HTTPS notification endpoint; owner authentication required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" } } } } } }, "responses": { "201": { "description": "Endpoint ID and one-time signing secret" } } } }, "/webhooks/{id}": { "delete": { "summary": "Disable an owned notification endpoint", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Disabled" } } } }, "/notifications": { "get": { "summary": "Poll durable account notifications", "parameters": [ { "in": "query", "name": "after", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Account events ordered by sequence" } } } }, "/webhook-deliveries": { "get": { "summary": "List attempts and exhausted webhook deliveries", "responses": { "200": { "description": "Delivery history" } } } }, "/webhook-replay": { "post": { "summary": "Replay an owned event to an active owned endpoint", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "eventId", "endpointId" ], "properties": { "eventId": { "type": "string" }, "endpointId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Queued for delivery" } } } }, "/funding/x402": { "post": { "summary": "Create an x402 v2 funding order (USDC on Base, eip155:8453); returns HTTP 402 with PAYMENT-REQUIRED", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amountCents" ], "properties": { "amountCents": { "type": "integer", "enum": [ 1000, 2500, 5000 ] } } } } } }, "responses": { "402": { "description": "Order created. Body has orderId/state/expiresAt/requirements; PAYMENT-REQUIRED header carries base64 requirements." } }, "description": "Agents pay for themselves. Creates a funding order and returns HTTP 402 with x402 v2 requirements (USDC on Base, eip155:8453). Point any x402 v2 client at the returned order URL; the credit lands on the same prepaid balance cards use. Proven live end to end. The @x402/fetch client refuses payments over $1 by default — call setSpendControls({maxAmountPerPayment:\"$50\"}). The wallet needs USDC only; the facilitator pays gas." } }, "/funding/x402/{orderId}": { "get": { "summary": "Funding order status (402 while awaiting payment, 200 otherwise)", "parameters": [ { "in": "path", "name": "orderId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "credited, expired or needs_review" }, "402": { "description": "awaiting_payment with requirements" } }, "description": "402 while awaiting payment, 200 once credited or expired. Safe to poll." }, "post": { "summary": "Pay the order: unsigned → 402 challenge; with PAYMENT-SIGNATURE (x402 v2) → settle and credit once", "parameters": [ { "in": "path", "name": "orderId", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "PAYMENT-SIGNATURE", "required": false, "schema": { "type": "string" }, "description": "base64 x402 v2 payment payload (X-PAYMENT also accepted). Omit to receive the 402 challenge." } ], "responses": { "200": { "description": "Settled and credited exactly once" }, "400": { "description": "invalid_payment_header, payment_requirements_mismatch, payment_destination_mismatch, payment_amount_mismatch, authorization_expired, payment_verification_failed, settlement_replayed" }, "402": { "description": "awaiting_payment; PAYMENT-REQUIRED header carries requirements" } }, "description": "Unsigned → 402 challenge (PAYMENT-REQUIRED header). With PAYMENT-SIGNATURE (x402 v2 EIP-3009 authorization) → verifies via the Coinbase facilitator, settles on Base, records a Stripe PaymentIntent, and credits exactly once. Returns PAYMENT-RESPONSE with the settlement receipt. Retry the same order after a timeout; never create a second order to pay again." } } } }