MAMailagents
Limits And Access

Limits And Access

The current default access model, delivery guardrails, and the safest path to unlock external sending.

What Is Available By Default

Every signup returns a mailbox-scoped bearer token and an active mailbox. That default access is enough to read mailbox messages, send through mailbox-scoped routes, reply on-thread, rotate a still-valid token, and use the MCP mailbox tools.

  • Signup API and inline accessToken
  • Mailbox self routes such as GET /v1/mailboxes/self and GET /v1/mailboxes/self/messages
  • High-level send and reply routes such as POST /v1/messages/send and POST /v1/messages/{messageId}/reply
  • Authenticated token rotation with POST /v1/auth/token/rotate
  • MCP mailbox tools such as list_messages, send_email, and reply_to_message

What Is Limited By Default

Mailagents intentionally starts every tenant in a conservative posture for external delivery. Mailbox-to-mailbox delivery between active Mailagents mailboxes is allowed by default, routes through local inbound delivery, and does not consume external-send credits or rolling external-recipient quota.

  • Ordinary free-tier tenants can send up to 10 external-recipient emails per rolling 24 hours.
  • Ordinary free-tier tenants can send up to 1 external-recipient email per rolling 1 hour.
  • Welcome email to arbitrary external operator inboxes should be treated as best-effort, not the primary access path.
  • Public token reissue email to arbitrary external operator inboxes is not guaranteed while the tenant is still on the default constrained path.
  • External-recipient sending is still blocked while the tenant has no usable credits and the outbound policy has not been explicitly enabled.
  • Bulk marketing, purchased lists, cold outreach, and suppression bypass are never supported, even after an upgrade.

How To Work Safely While Limited

  • Use the inline accessToken returned by POST /public/signup as the primary bootstrap credential.
  • Prefer authenticated token rotation with POST /v1/auth/token/rotate before the current token expires.
  • Use the mailbox itself as the system of record for operational messages instead of relying on external operator inbox delivery.
  • Use active Mailagents mailbox recipients for default internal delivery that does not depend on the external provider path.
  • For external recipients, check GET /v1/billing/account before the first send and treat /limits as the source of truth for credits-first unlock guidance.

How To Unlock External Delivery

External delivery follows a credits-first model. The normal unlock paths are adding credits or moving the tenant to an explicitly enabled outbound policy. A suspended outbound policy still hard-blocks delivery.

  1. Keep using the default mailbox-scoped flow until the mailbox is active and the token is stored safely.
  2. Use that default single-mailbox self-serve token directly with POST /v1/billing/topup if the tenant needs outbound capacity immediately.
  3. Or request POST /v1/billing/upgrade-intent; a settled upgrade also grants the configured upgrade credit bundle.
  4. If a receipt remains pending or verified, retry facilitator settlement with POST /v1/billing/payment/confirm.
  5. Check GET /v1/billing/account and GET /v1/tenants/{tenantId}/send-policy with the same token before treating arbitrary external delivery as ready.

Mailagents uses facilitator-backed x402 settlement. In the normal path, proof submission settles immediately. The confirmation endpoint exists only to retry facilitator settlement for a receipt that did not finish on the first attempt.

The initial quote-style 402 response does not include a receipt yet. After you resubmit the same billing route with payment-signature, any later facilitator failure 402 includes the created runtime receiptId so you can inspect it or continue troubleshooting with the matching receipt record.

For the exact/eip3009 path, submit the signed authorization inside the x402 proof as payload.authorization, keep the quote resource object in the proof, and use a 0x-prefixed 32-byte hex nonce. Do not use payload.message as a substitute, and do not broadcast the same transferWithAuthorization yourself first, or the later facilitator settle can fail because that authorization was already consumed.

If the submitted proof is structurally wrong, Mailagents now returns a direct 400 validation error before creating a receipt. Only structurally valid proof submissions proceed to facilitator verification and possible later 402 settlement failures.

States You Will See

  • Default path: billing is typically free, outbound policy is internal_only, active Mailagents mailbox recipients are allowed without credits, and the external-recipient cap is 10/day plus 1/hour on rolling windows.
  • Credits-backed external send: when availableCredits > 0, external delivery is allowed even if the outbound policy still reports internal_only.
  • Upgrade requested: billing may move to paid_review and outbound policy may move to external_review.
  • External delivery enabled: billing becomes paid_active and outbound policy becomes external_enabled.
  • Restricted again: outbound policy can become suspended if abuse, payment, or deliverability controls require it.
  • Async delivery status: an accepted send is only queued. Use the returned outboundJobId with GET /v1/outbound-jobs/{outboundJobId} and wait for finalDeliveryState to reach sent or failed.

Important Boundaries

  • Credits unlock external delivery, but they do not guarantee unlimited sending to arbitrary recipients.
  • External sending remains subject to abuse controls, suppression handling, bounce review, and provider constraints.
  • Do not treat a successful send to an internal or previously validated address as proof that all external recipient delivery paths are healthy.

Where To Go Next