# ClawMail signup: Link is the default payment option

Check https://clawmail.xyz/api/payments/link first. Continue only when enabled is true.
Crypto is the secondary option: POST /api/mailboxes/crypto, $1 USDC on Base, with address and walletAddress.
POST /api/mailboxes/link remains an alias for Link signup.
Price: $1 USD once. Includes a permanent custom or generated email address and unlimited incoming messages.
No crypto wallet is required. Link Agent Wallet currently requires a US Link account.
Save your email address and original cm_link_ API key in durable secret storage before payment. This is the Idempotency-Key used at signup and your Bearer token for inbox access. Losing or revoking it loses access; there is no self-service recovery or rotation. Link mailboxes do not require a crypto wallet key pair.
For free or crypto signup: Keep your original wallet key pair: securely back up the private key or recovery phrase and save its public wallet address with your email address. You must retain access to that same wallet to sign in after the bootstrap token expires. The public address alone cannot restore access. Never send the private key or recovery phrase to ClawMail. There is no self-service recovery for a lost wallet.

1. Generate a mailbox API key ONCE and save it in durable secret storage:
   CLAWMAIL_API_KEY="cm_link_$(openssl rand -hex 32)"
   Never regenerate this key while retrying an uncertain payment.

2. Connect the owner's Link account and authorize spending through Link:
   npx @stripe/link-cli auth login

3. Purchase your chosen permanent address (replace your-agent with an available local part):
   npx @stripe/link-cli mpp pay https://clawmail.xyz/api/mailboxes \
     --method POST --data '{"address":"your-agent"}' \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: $CLAWMAIL_API_KEY" \
     --context "Purchase one ClawMail email inbox for this AI agent for one dollar USD, with unlimited incoming messages and API key access."

Omit address (send {}) to get a generated permanent address instead. Both have the same price and unlimited messages.
Address format: 1–64 letters, numbers, dots, underscores or hyphens; start and end with a letter or number.
Names are normalized to lowercase. Availability checks do not reserve names; ownership begins after successful payment.

This follows an MPP HTTP 402 challenge using a Link Shared Payment Token.
For sandbox credentials, use Link CLI test mode. Never use a live payment for a test without authorization.
Official buyer documentation: https://github.com/stripe/link-cli

4. Read messages at the returned email address:
   curl 'https://clawmail.xyz/api/mailboxes/RETURNED_EMAIL/messages' \
     -H "Authorization: Bearer $CLAWMAIL_API_KEY"
Use the same key as the token argument of ClawMail MCP inbox tools (address is the local part).

Recovery: POST the same body (or omit address to recover its saved value) with the SAME Idempotency-Key.
An already-paid order returns 200 with its mailbox and Payment-Receipt, without another charge.
Initial creation returns 201. Retrying an uncertain payment requires the same payment credential.
409 address_unavailable: this attempt was not charged; choose a different address with a new key. If an earlier attempt had an uncertain payment, reconcile it first.
409 order_address_mismatch: the key is already bound to another name; retry that name or use a new key for a new purchase.
409 order_refunded: an earlier successful charge could not be fulfilled after a server failure and its refund was initiated.
An expired unresolved order also returns 409; reconcile with support before starting another order.
Keep the nonsecret orderId from an error response for support; never share the API key or payment token.

RENEW AN EXPIRED MAILBOX (only addresses explicitly enrolled in expiry):
An authenticated inbox query returns HTTP 402 with code mailbox_expired and the renewal endpoint. MCP tools return the same structured error.
Present the $1 USD / 30 days renewal request to the user before spending unless they already authorized it.
Keep the existing mailbox token in CLAWMAIL_MAILBOX_TOKEN. Wallet owners can log in again with their original wallet if the session token expired.
Generate a separate payment retry key ONCE: CLAWMAIL_RENEWAL_KEY="cm_link_$(openssl rand -hex 32)"
   npx @stripe/link-cli mpp pay https://clawmail.xyz/api/mailboxes/YOUR_ADDRESS/renew \
     --method POST --data '{}' \
     --header "Content-Type: application/json" \
     --header "X-Mailbox-Token: $CLAWMAIL_MAILBOX_TOKEN" \
     --header "Idempotency-Key: $CLAWMAIL_RENEWAL_KEY" \
     --context "Renew this existing ClawMail mailbox for one dollar USD for 30 days."
Retain both headers on the payment retry. Authorization: Payment is reserved for the MPP credential.
Renewal returns renewed: true and accessExpiresAt. Retry the inbox query with the ORIGINAL mailbox credentials; the renewal key does not grant inbox access.
Repeated requests and webhook deliveries for the same order restore access only once. A later renewal needs a fresh renewal key.
Each payment adds 30 days from the later of now or the current access expiry. There is no automatic recurring charge.
Expiry restricts inbox reads and deletes; it preserves the address, stored messages and credentials. Incoming mail continues under the existing receive limits.
Mailboxes without an access expiry keep their existing plan and do not need renewal.

The API key lasts until revoked. POST /api/auth/logout permanently revokes it.
There is currently no self-service key recovery or rotation; save your key before payment.