Usage, limits, and plan

GET/v1/billing

Secret key — sk_… or sk_test_… · Base URL https://api.volanea.com

Current-month usage, the monthly caps, the plan and its per-cycle email quota, computed reputation, and subscription state in one call.

Response

200 · Billing

monthstringrequired
Current period, "YYYY-MM".
usedintegerrequired
Non-test emails sent this month.
limitinteger | null
Overall monthly send cap; `null` = unlimited.
categoriesobject
Per-category usage and cap — transactional/campaign/workflow/inbound. Checked alongside (not instead of) the overall `limit`.
- transactionalobject
  - limitinteger | nullrequired
    `null` = unlimited.
  - usedintegerrequired
    Non-test sends this month in this category.
- campaignobject
  - limitinteger | nullrequired
    `null` = unlimited.
  - usedintegerrequired
    Non-test sends this month in this category.
- workflowobject
  - limitinteger | nullrequired
    `null` = unlimited.
  - usedintegerrequired
    Non-test sends this month in this category.
- inboundobject
  - limitinteger | nullrequired
    `null` = unlimited.
  - usedintegerrequired
    Non-test sends this month in this category.
planenumrequired
freestartergrowth
emailQuotaintegerrequired
Email credits per monthly cycle for the current plan. Hard cap — sending stops when it's used up.
freeTierCreditsinteger
creditsUsedintegerrequired
Credits used this cycle (1/email, 2 with attachments).
planQuotasobject
Per-cycle quota of every self-serve plan — what an upgrade would buy.
- freeinteger
- starterinteger
- growthinteger
reputationobject
Computed deliverability metrics. The worst of three windows (24h/7d/all-time) wins; `windows` breaks each one down. New projects (<30 days old) enforce at a lower volume floor.
reputationStateenumrequired
okwarnthrottledpaused
reputationReasonstring | null
dodoobject
Merchant-of-record provider (Dodo Payments) backing paid subscriptions. Disabled on self-host installs.
- enabledboolean
- envenum
  test_modelive_mode
dodoSubscriptionobject
- idstring | null
- statusenum
  activeendednull
- planenum
  startergrowthnull
- cancelAtNextBillingDateboolean
- nextBillingAtstring | null

Errors

Every failure returns the standard envelope — branch on `code`, never on the wording of `error`.

401Missing or invalid API key.

Request

curl https://api.volanea.com/v1/billing \
  -H "Authorization: Bearer sk_..."

Response

200 · application/json

{
  "success": true,
  "data": {
    "month": "<month>",
    "used": 1,
    "limit": 1,
    "categories": {
      "transactional": {
        "limit": 1,
        "used": 1
      },
      "campaign": {
        "limit": 1,
        "used": 1
      },
      "workflow": {
        "limit": 1,
        "used": 1
      },
      "inbound": {
        "limit": 1,
        "used": 1
      }
    },
    "plan": "free",
    "emailQuota": 1,
    "freeTierCredits": 1,
    "creditsUsed": 1,
    "planQuotas": {
      "free": 1,
      "starter": 1,
      "growth": 1
    },
    "reputation": {},
    "reputationState": "ok",
    "reputationReason": "<reputationReason>",
    "dodo": {
      "enabled": true,
      "env": "test_mode"
    },
    "dodoSubscription": {
      "id": "<id>",
      "status": "active",
      "plan": "starter",
      "cancelAtNextBillingDate": true,
      "nextBillingAt": "2026-01-01T09:00:00.000Z"
    }
  }
}

92 endpoints · OpenAPI document