Production Agents Guide

Operate the live mail system, not the test scaffold.

This guide is the production operating contract for agents. Use the live endpoints, assume strict wallet authentication, request short-lived HMAC payment proofs when you are over free limits, and always release mailboxes when the workflow is complete.

Open User App Open Admin Dashboard Open Webmail

API Base

api.mailagents.net

All production API calls should target https://api.mailagents.net.

Auth Mode

SIWE strict

Agents must sign the SIWE challenge with a real wallet. Do not assume mock signatures work in production.

Payment Mode

HMAC proof

When free limits are exceeded, protected endpoints require a short-lived payment proof issued by the backend.

Mail Domain

inbox.mailagents.net

Allocated mailboxes, Webmail login, and SMTP/IMAP credentials are issued against the live mail domain.

Cooldown

10 / 24h

If a tenant is created without a bound wallet identity, outbound send is capped at 10 messages in the first 24 hours. Bind a wallet to remove the cooldown.

Direct Production Flow

Set the live base URL

export API_BASE="https://api.mailagents.net"

Request a SIWE challenge

curl -s "$API_BASE/v2/auth/siwe/challenge" \
  -H 'content-type: application/json' \
  -d '{"wallet_address":"0xYOUR_WALLET"}'

Sign the returned message using the live wallet on the configured chain.

Verify the signature and store the session

curl -s "$API_BASE/v2/auth/siwe/verify" \
  -H 'content-type: application/json' \
  -d '{"message":"<challenge_message>","signature":"<wallet_signature>"}'

Persist access_token, agent_id, tenant_id, and did.

Allocate a mailbox

curl -s "$API_BASE/v2/mailboxes/leases" \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer <access_token>' \
  -H 'x-payment-proof: <x_payment_proof>' \
  -d '{"agent_id":"<agent_id>","purpose":"signup","ttl_hours":1}'

Persist lease_id, mailbox_id, account_id, address, expires_at, and any issued login details.

Ask the backend for a payment proof (when over free limits)

curl -s "$API_BASE/v2/payments/proof" \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer <access_token>' \
  -d '{"method":"POST","path":"/v2/mailboxes/leases"}'

Use the returned x_payment_proof value exactly as the x-payment-proof header.

Execution Rules

Use the live UI when possible.

For browser-based operation, open https://api.mailagents.net/app. It already handles runtime detection, wallet connect, mailbox selection, webhook setup, usage lookup, and send-mail flow.

Do not use mock assumptions.

Production is currently running with strict SIWE and HMAC billing proofs. Local shortcuts such as mock-proof or fake signatures are not valid on the live deployment.

Persist these fields per run.

access_token
agent_id
tenant_id
mailbox_id
address
webmail_password

Endpoints that may require payment proofs after free limits.

POST /v2/mailboxes/leases
GET /v2/messages
POST /v2/messages/send
POST /v2/webhooks

Read, Send, Release

Fetch latest messages

curl -s "$API_BASE/v2/payments/proof" \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer <access_token>' \
  -d '{"method":"GET","path":"/v2/messages"}'

curl -s "$API_BASE/v2/messages?mailbox_id=<mailbox_id>&limit=10" \
  -H 'authorization: Bearer <access_token>' \
  -H 'x-payment-proof: <latest_messages_proof>'

Rotate credentials only if the user wants a new password

If the allocate response already returned webmail_password, agents can send mail with that password directly. Use reset only for explicit rotation or password recovery.

curl -s "$API_BASE/v2/mailboxes/accounts/<account_id>/credentials/reset" \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer <access_token>'

Send mail through the live HTTP API

curl -s "$API_BASE/v2/payments/proof" \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer <access_token>' \
  -d '{"method":"POST","path":"/v2/messages/send"}'

curl -s "$API_BASE/v2/messages/send" \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer <access_token>' \
  -H 'x-payment-proof: <send_proof>' \
  -d '{"mailbox_id":"<mailbox_id>","to":"[email protected]","subject":"agent send api","text":"hello from production agent","mailbox_password":"<webmail_password>"}'

Release the mailbox when done

curl -s "$API_BASE/v2/mailboxes/leases/<lease_id>/release" \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer <access_token>'

Agent Operating Checklist

Start with /v2/meta/runtime or the live UI to confirm current chain and auth mode.
Use a real browser wallet for SIWE signing. Keep chain alignment with the runtime metadata.
When you are over free limits, request a fresh payment proof immediately before each protected call; proofs are short-lived.
Read from /v2/messages for parsed OTP and verification-link workflows.
Issue or reset mailbox credentials before using Webmail, SMTP, or the send API.
Create webhooks through POST /v2/webhooks when downstream automation needs push delivery.
Open /admin when you need operator visibility into tenants, webhooks, invoices, risk events, or audit logs.
Release the mailbox after the run so the lease does not remain occupied unnecessarily.

Production Endpoints

https://api.mailagents.net/app
https://api.mailagents.net/admin
https://api.mailagents.net/v2/meta/runtime
https://inbox.mailagents.net/webmail/

What this page is for

This page is the production instruction surface for agents. If an agent follows the steps on this page, it should be able to authenticate, allocate a mailbox, read OTP mail, send mail, and close the lease against the live deployment.