tinysend
sign in

Agent payments — tinysend agents

tinysend meters sent emails per calendar month. Agents can check usage, raise their limit by claiming an identity, subscribe to a paid plan over the API, or pay for overage inline — all without a human in the loop. A human fallback URL is always included.

Limits

  • anonymous agent: 10 emails/month
  • claimed (email verified): 100 emails/month
  • light: 2,000 emails/month ($6/mo)
  • plus: 10,000 emails/month ($19/mo)
  • max: 30,000 emails/month ($49/mo)

See pricing for the full plan comparison.

Check usage

GET https://api.tinysend.com/v1/usage
Authorization: Bearer sk_...

Returns plan, period_start, period_end, emails_included, emails_sent, emails_remaining, and an overage object (enabled, count, rate, cost, cap, cap_remaining). Check emails_remaining before a big send.

What a 402 looks like

When you hit your monthly limit, send endpoints return HTTP 402:

{
  "error": {
    "code": "limit_exceeded",
    "message": "monthly email limit reached",
    "upgrade_url": "https://app.tinysend.com/billing",
    "enable_overage_url": "https://tinysend.com/settings",
    "payment": {
      "protocol": "MPP",
      "docs": "https://mpp.dev",
      "hint": "retry with Payment credential to pay inline"
    }
  }
}

You may also see code: "spending_cap_reached" (402) when overage is enabled but the monthly spending cap is used up — it includes cap and increase_cap_url.

How to handle it

In order of preference:

  1. claim an identity — if you’re anonymous (10/month), verifying an email bumps you to 100/month. See claiming.

  2. subscribe programmatically — if you have a Stripe payment method (e.g. a virtual card):

POST https://api.tinysend.com/v1/billing/subscribe
Authorization: Bearer sk_...

{ "plan": "light", "payment_method_id": "pm_..." }

plan is light, plus, or max. Returns 201 with subscription_id, plan, status, current_period_end — or 409 already_subscribed if a subscription exists.

  1. pay overage inline via MPP — over-limit sends can be paid per request using the Machine Payments Protocol at $0.003/email with a $0.50 minimum charge (Stripe card minimum). The 402 carries the MPP challenge; retry the request with a Payment credential and it proceeds.

  2. hand off to a human — every 402 includes upgrade_url. Surface it to your operator and they can upgrade with a normal checkout.

Questions?

Contact us at hi@tinysend.com.