{"openapi":"3.1.0","info":{"title":"Mail","version":"1.0.0","description":"Disposable email inboxes for agents — create, receive, read, and send email. Handy for signups, verification codes, and OTPs. Pay per call.","contact":{"email":"support@payweave.app"},"x-guidance":"Disposable email inboxes for agents — create, receive, read, and send email. Handy for signups, verification codes, and OTPs. Pay per call.\nEach endpoint takes a JSON request and returns either a 200 with the result or a 402 Payment Required challenge (MPP / x402). Pricing is fixed per endpoint in USD; the per-operation `x-payment-info` block carries the exact challenge metadata (price, accepted protocols, payment realm).\nFor per-endpoint schemas, examples, and detailed usage, fetch https://api.payweave.app/app/app_n885eg97q5gcnai80k8x8xwi/skill.md or `<this-origin>/<path>/skill.md` for a single endpoint."},"x-service-info":{"categories":["Email","Agent infrastructure","Verification"]},"servers":[{"url":"https://mail.payweave.services"}],"paths":{"/inboxes":{"get":{"summary":"Email: List Inboxes","description":"Free (identity-only) list of every inbox owned by the paying wallet, across all TTL tiers (random + vanity). Sign the $0 challenge to prove wallet ownership; no charge.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.000000"},"protocols":[{"mpp":{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","network":"eip155:4217","amount":"0"}},{"mpp":{"method":"solana","intent":"charge","currency":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","amount":"0"}},{"x402":{"scheme":"exact","network":"eip155:8453","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","amount":"0","extra":{"name":"USD Coin","version":"2"}}},{"x402":{"scheme":"exact","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","currency":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","amount":"0"}}],"description":"Free (identity-only) list of every inbox owned by the paying wallet, across all TTL tiers (random + vanity). Sign the $0 challenge to prove wallet ownership; no charge."},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"inboxes":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"address":{"type":"string"},"ttl_days":{"type":"integer"},"expires_at":{"type":"string"},"webhook_configured":{"type":"boolean"}},"required":["slug","address","ttl_days","expires_at","webhook_configured"],"additionalProperties":false}}},"required":["inboxes"],"additionalProperties":false}}}},"402":{"description":"Payment Required"}}},"post":{"summary":"Email: Create Inbox","description":"Create a disposable email inbox. Returns an address you can publish anywhere and read messages from via this API. TTL tier (1 / 7 / 30 / 90 days, default 30) drives both price ($0.002–$0.020 USDC) and inbox lifetime — R2 lifecycle deletes the inbox and its messages at expiry. Optional `local_part` reserves a globally-unique vanity address (`<local_part>@<EMAIL_DOMAIN>`, 30/90-day TTL, flat $0.10) — call the free `GET /inboxes/available?local_part=…` first to confirm it is free (if taken, create refunds and returns 409). Optional `webhook_url` fires HMAC-signed POSTs on every new inbound message. The returned `webhook_secret` is shown exactly once; store it to verify webhook signatures.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.002000"},"protocols":[{"mpp":{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","network":"eip155:4217","amount":"2000"}},{"mpp":{"method":"solana","intent":"charge","currency":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","amount":"2000"}},{"x402":{"scheme":"exact","network":"eip155:8453","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","amount":"2000","extra":{"name":"USD Coin","version":"2"}}},{"x402":{"scheme":"exact","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","currency":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","amount":"2000"}}],"description":"Create a disposable email inbox. Returns an address you can publish anywhere and read messages from via this API. TTL tier (1 / 7 / 30 / 90 days, default 30) drives both price ($0.002–$0.020 USDC) and inbox lifetime — R2 lifecycle deletes the inbox and its messages at expiry. Optional `local_part` reserves a globally-unique vanity address (`<local_part>@<EMAIL_DOMAIN>`, 30/90-day TTL, flat $0.10) — call the free `GET /inboxes/available?local_part=…` first to confirm it is free (if taken, create refunds and returns 409). Optional `webhook_url` fires HMAC-signed POSTs on every new inbound message. The returned `webhook_secret` is shown exactly once; store it to verify webhook signatures."},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","format":"email","description":"Disposable email address. Receive mail here."},"slug":{"type":"string","description":"Inbox slug. Use in list/get/send route paths."},"ttl_days":{"type":"integer","description":"TTL tier: 1, 7, 30, or 90."},"expires_at":{"type":"string","description":"ISO-8601. R2 lifecycle deletes the inbox and its messages at this time."},"display_name":{"type":"string","description":"Friendly From display name, when set. Default sender name on send."},"webhook_url":{"type":"string","format":"uri"},"webhook_secret":{"type":"string","description":"Returned only when a webhook is configured. Save it now — used to verify HMAC on incoming webhook POSTs. Never returned again."}},"required":["address","slug","ttl_days","expires_at"],"additionalProperties":false}}}},"402":{"description":"Payment Required"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ttl_days":{"type":"number","enum":[1,7,30,90]},"webhook_url":{"type":"string","format":"uri"},"local_part":{"type":"string","minLength":3,"maxLength":32},"display_name":{"type":"string","minLength":1,"maxLength":64}},"additionalProperties":false}}}}}},"/inboxes/{slug}/extend":{"post":{"summary":"Email: Extend Inbox","description":"Renew an inbox for another full TTL period, keeping the same address and tier. Resets the expiry to now + ttl_days and keeps existing messages alive. Wallet must own the inbox.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.002000"},"protocols":[{"mpp":{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","network":"eip155:4217","amount":"2000"}},{"mpp":{"method":"solana","intent":"charge","currency":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","amount":"2000"}},{"x402":{"scheme":"exact","network":"eip155:8453","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","amount":"2000","extra":{"name":"USD Coin","version":"2"}}},{"x402":{"scheme":"exact","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","currency":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","amount":"2000"}}],"description":"Renew an inbox for another full TTL period, keeping the same address and tier. Resets the expiry to now + ttl_days and keeps existing messages alive. Wallet must own the inbox."},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"ttl_days":{"type":"integer"},"expires_at":{"type":"string","description":"New expiry after renewal (now + ttl_days)."}},"required":["slug","ttl_days","expires_at"],"additionalProperties":false}}}},"402":{"description":"Payment Required"}},"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"not":{}},{"type":"object","properties":{},"additionalProperties":false}]}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}]}},"/inboxes/{slug}/messages":{"get":{"summary":"Email: List Messages","description":"List the messages received by one of your inboxes. Wallet-scoped: 404 if the inbox is not owned by the paying wallet.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001000"},"protocols":[{"mpp":{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","network":"eip155:4217","amount":"1000"}},{"mpp":{"method":"solana","intent":"charge","currency":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","amount":"1000"}},{"x402":{"scheme":"exact","network":"eip155:8453","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","amount":"1000","extra":{"name":"USD Coin","version":"2"}}},{"x402":{"scheme":"exact","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","currency":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","amount":"1000"}}],"description":"List the messages received by one of your inboxes. Wallet-scoped: 404 if the inbox is not owned by the paying wallet."},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":["string","null"]},"subject":{"type":["string","null"]},"received_at":{"type":"string"},"size":{"type":"integer","minimum":0}},"required":["id","from","subject","received_at","size"],"additionalProperties":false}},"cursor":{"type":["string","null"]}},"required":["messages","cursor"],"additionalProperties":false}}}},"402":{"description":"Payment Required"}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}]}},"/inboxes/{slug}/messages/{id}":{"get":{"summary":"Email: Read Message","description":"Read a single message — parsed headers, text, html, and signed-once URLs to attachment bodies. Wallet-scoped: 404 if the inbox is not owned by the paying wallet.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001000"},"protocols":[{"mpp":{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","network":"eip155:4217","amount":"1000"}},{"mpp":{"method":"solana","intent":"charge","currency":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","amount":"1000"}},{"x402":{"scheme":"exact","network":"eip155:8453","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","amount":"1000","extra":{"name":"USD Coin","version":"2"}}},{"x402":{"scheme":"exact","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","currency":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","amount":"1000"}}],"description":"Read a single message — parsed headers, text, html, and signed-once URLs to attachment bodies. Wallet-scoped: 404 if the inbox is not owned by the paying wallet."},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"received_at":{"type":"string"},"message_id":{"type":["string","null"]},"from":{"type":["string","null"]},"to":{"type":"array","items":{"type":"string"}},"cc":{"type":"array","items":{"type":"string"}},"subject":{"type":["string","null"]},"date":{"type":["string","null"]},"text":{"type":["string","null"]},"html":{"type":["string","null"]},"headers":{"type":"object","additionalProperties":{"type":"string"}},"attachments":{"type":"array","items":{"type":"object","properties":{"filename":{"type":"string"},"content_type":{"type":"string"},"size":{"type":"integer","minimum":0},"url":{"type":"string","description":"Short-lived (1-hour) signed download URL for the attachment body. Fetch with a plain GET — no payment required."}},"required":["filename","content_type","size","url"],"additionalProperties":false}}},"required":["id","slug","received_at","message_id","from","to","cc","subject","date","text","html","headers","attachments"],"additionalProperties":false}}}},"402":{"description":"Payment Required"}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/inboxes/{slug}/messages/{id}/delete":{"post":{"summary":"Email: Delete Message","description":"Free (identity-only) delete of a single message and its attachments. Sign the $0 challenge to prove wallet ownership; no charge. 404 if the inbox/message is not owned by the caller.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.000000"},"protocols":[{"mpp":{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","network":"eip155:4217","amount":"0"}},{"mpp":{"method":"solana","intent":"charge","currency":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","amount":"0"}},{"x402":{"scheme":"exact","network":"eip155:8453","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","amount":"0","extra":{"name":"USD Coin","version":"2"}}},{"x402":{"scheme":"exact","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","currency":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","amount":"0"}}],"description":"Free (identity-only) delete of a single message and its attachments. Sign the $0 challenge to prove wallet ownership; no charge. 404 if the inbox/message is not owned by the caller."},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"],"additionalProperties":false}}}},"402":{"description":"Payment Required"}},"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"not":{}},{"type":"object","properties":{},"additionalProperties":false}]}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/inboxes/{slug}/send":{"post":{"summary":"Email: Send","description":"Send an email from one of your inboxes via Cloudflare Email Service. The `from` is locked to the inbox's own address (`<slug>@<EMAIL_DOMAIN>`); the wallet must own the slug. Sends multipart/alternative (a plain-text part is auto-derived from `html` when omitted) and attaches a one-click `List-Unsubscribe` header — recipients who unsubscribe are dropped from future sends. Set a friendly From name via the inbox `display_name` or per-message `from_name`. Upstream cost: $0.00035 per send (5.7× margin at $0.002). Requires the sender domain to be verified in the Cloudflare dashboard.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.002000"},"protocols":[{"mpp":{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","network":"eip155:4217","amount":"2000"}},{"mpp":{"method":"solana","intent":"charge","currency":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","amount":"2000"}},{"x402":{"scheme":"exact","network":"eip155:8453","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","amount":"2000","extra":{"name":"USD Coin","version":"2"}}},{"x402":{"scheme":"exact","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","currency":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","amount":"2000"}}],"description":"Send an email from one of your inboxes via Cloudflare Email Service. The `from` is locked to the inbox's own address (`<slug>@<EMAIL_DOMAIN>`); the wallet must own the slug. Sends multipart/alternative (a plain-text part is auto-derived from `html` when omitted) and attaches a one-click `List-Unsubscribe` header — recipients who unsubscribe are dropped from future sends. Set a friendly From name via the inbox `display_name` or per-message `from_name`. Upstream cost: $0.00035 per send (5.7× margin at $0.002). Requires the sender domain to be verified in the Cloudflare dashboard."},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"message_id":{"type":"string"},"accepted_at":{"type":"string"},"skipped":{"type":"array","items":{"type":"string"},"description":"Recipients dropped because they previously unsubscribed from this inbox."}},"required":["message_id","accepted_at"],"additionalProperties":false}}}},"402":{"description":"Payment Required"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"anyOf":[{"type":"string","format":"email"},{"type":"array","items":{"type":"string","format":"email"},"minItems":1,"maxItems":50}]},"cc":{"type":"array","items":{"type":"string","format":"email"},"maxItems":50},"bcc":{"type":"array","items":{"type":"string","format":"email"},"maxItems":50},"reply_to":{"type":"string","format":"email"},"from_name":{"type":"string","minLength":1,"maxLength":64},"subject":{"type":"string","minLength":1,"maxLength":998},"text":{"type":"string","maxLength":1048576},"html":{"type":"string","maxLength":1048576},"headers":{"type":"object","additionalProperties":{"type":"string"}}},"required":["to","subject"],"additionalProperties":false}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}]}},"/inboxes/{slug}/status":{"get":{"summary":"Email: Inbox Status","description":"Free (identity-only) inbox status: existence, expiry, message count, and whether a webhook is configured. Sign the $0 challenge to prove wallet ownership; no charge. Use this to poll cheaply instead of paying per list.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.000000"},"protocols":[{"mpp":{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","network":"eip155:4217","amount":"0"}},{"mpp":{"method":"solana","intent":"charge","currency":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","amount":"0"}},{"x402":{"scheme":"exact","network":"eip155:8453","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","amount":"0","extra":{"name":"USD Coin","version":"2"}}},{"x402":{"scheme":"exact","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","currency":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","amount":"0"}}],"description":"Free (identity-only) inbox status: existence, expiry, message count, and whether a webhook is configured. Sign the $0 challenge to prove wallet ownership; no charge. Use this to poll cheaply instead of paying per list."},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"exists":{"type":"boolean"},"slug":{"type":"string"},"address":{"type":"string"},"ttl_days":{"type":"integer"},"expires_at":{"type":"string"},"message_count":{"type":"integer","minimum":0},"webhook_configured":{"type":"boolean"}},"required":["exists","slug","address","ttl_days","expires_at","message_count","webhook_configured"],"additionalProperties":false}}}},"402":{"description":"Payment Required"}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}]}},"/inboxes/{slug}/update":{"post":{"summary":"Email: Update Inbox","description":"Free (identity-only) inbox config update. Set/replace `webhook_url` (a fresh `webhook_secret` is returned once) or `display_name` (the From name on outbound mail), or pass null to remove either; omit a field to leave it unchanged. Sign the $0 challenge to prove wallet ownership; no charge.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.000000"},"protocols":[{"mpp":{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","network":"eip155:4217","amount":"0"}},{"mpp":{"method":"solana","intent":"charge","currency":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","amount":"0"}},{"x402":{"scheme":"exact","network":"eip155:8453","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","amount":"0","extra":{"name":"USD Coin","version":"2"}}},{"x402":{"scheme":"exact","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","currency":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","amount":"0"}}],"description":"Free (identity-only) inbox config update. Set/replace `webhook_url` (a fresh `webhook_secret` is returned once) or `display_name` (the From name on outbound mail), or pass null to remove either; omit a field to leave it unchanged. Sign the $0 challenge to prove wallet ownership; no charge."},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"webhook_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"display_name":{"type":["string","null"]},"webhook_secret":{"type":"string","description":"Returned once when a new webhook URL is set. Save it to verify HMAC signatures."}},"required":["slug","webhook_url","display_name"],"additionalProperties":false}}}},"402":{"description":"Payment Required"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"webhook_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"display_name":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"null"}]}},"additionalProperties":false}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}]}}}}