> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Mail spending controls

> Inspect recipient allowance and reserve capped Mail-only prepaid credit without automatic additional spending.

<Warning>
  **Live with caveats.** This area is real and usable, but the docs intentionally call out operational or UX limits that still matter.
</Warning>

## Goal

Inspect recipient allowance and reserve capped Mail-only prepaid credit without automatic additional spending.

## Prerequisites

* Keep Mail credentials on your backend. API examples use [https://api.stackshift.cloud/v1](https://api.stackshift.cloud/v1) unless a public /api/v1 route is stated.

## Workflow

<Steps>
  <Step>
    Read the billing summary and actual rate availability.
  </Step>

  <Step>
    Choose hard stop or explicitly enable prepaid with a positive period cap as billing owner.
  </Step>

  <Step>
    Fund through verified checkout and review the full campaign estimate.
  </Step>

  <Step>
    Approve the maximum, send or schedule, and monitor reservations and alerts.
  </Step>
</Steps>

## Activation is explicit

Billing code is implemented, but no launch prices are seeded. Monetary pricing is unavailable until an administrator publishes and explicitly activates a valid NGN rate card. Before activation, existing sending restrictions remain in effect. Do not interpret zero-valued rate fields as an advertised free live-mail rate.

* All API money amounts are integer kobo: 100 kobo = NGN 1. The dashboard displays the recipient price per 1,000. Read the active rate rather than hard-coding a price from an example.
* A billing period snapshots its rate and included recipients. Existing subscriptions use their subscription period; accounts without one use UTC calendar months. Publishing a later rate does not retroactively change an existing period.
* Mail credit cannot fund infrastructure, and shared cloud credit cannot fund Mail. There is no postpaid debt or automatic top-up. Funding alone never opts a workspace into spending.

## Summary and estimate response

* GET /mail/billing returns active, mode, currency, periodStart, periodEnd, rateVersion, recipientPriceKobo, included, used, reserved, remaining, prepaidBalanceKobo, spentKobo, reservedKobo, reconciliationRequired and settings. settings contains prepaidEnabled, capKobo and revision.
* used and reserved count recipients, while spentKobo and reservedKobo count money. remaining is the included allowance still available for new reservations. Inspect reserved funds as well as settled spending before deciding whether a cap has room.
* GET /mail/campaigns/\{id}/estimate adds recipientCount, requiredCreditKobo and blockingReasons. The amount is max(0, recipientCount - remaining) × recipientPriceKobo. An estimate is not a reservation and can change before dispatch.
* blockingReasons can contain pricing\_unavailable, payment\_reconciliation\_required, prepaid\_not\_enabled, insufficient\_mail\_credit and period\_cap\_exceeded. Multiple reasons can apply. pricing\_unavailable means pricing is not activated; existing pre-activation sending restrictions still govern live sends. Test estimates need no paid credit.

```ts theme={null}
const summary = await client.mail.billing.summary()
const estimate = await client.mail.campaigns.estimate(campaign.id)
if (estimate.mode === 'live' && !estimate.active) {
  console.log('Monetary pricing is not activated; inspect current Mail sending limits.')
} else if (estimate.blockingReasons.length) {
  console.log(estimate.blockingReasons)
} else {
  // Only after the operator reviews this cost and the current campaign revision:
  await client.mail.campaigns.send(campaign.id, campaign.revision, estimate.requiredCreditKobo)
}
```

## Owner settings and top-ups

* PUT /v1/mail/billing/settings accepts prepaidEnabled, capKobo and the current revision. Enabling prepaid requires a positive cap; cap covers the billing period. Reload settings after mail\_billing\_conflict (HTTP 409).
* POST /v1/mail/billing/topups accepts amountKobo (1–2,000,000,000), idempotencyKey (nonzero UUID) and optional provider. The response contains reference, authorization\_url and status. Open the returned checkout URL rather than constructing a provider URL.
* POST /v1/mail/billing/topups/verify accepts \{reference}. The server verifies provider, successful payment status, reference, amount and currency before issuing Mail credit. The return redirect alone is not proof of payment. Reusing an idempotency key for a different amount is rejected.
* Settings, checkout and verification require the signed-in billing owner in Live mode. API-token authentication is rejected with HTTP 403 billing\_owner\_required, even if the token has broad scopes. These writes intentionally have no server-key SDK wrapper; use Mail → Spending.
* GET /mail/billing and campaign estimates are exposed by the Go, JavaScript and Python SDKs. Test mode can read its free summary despite exhausted live allowance.

## Reservation and delivery accounting

* Each message counts unique envelope recipients across To/Cc/Bcc. Immediate sends and batches reserve included allowance and any permitted prepaid amount atomically before acceptance. Idempotent retries do not reserve or charge twice.
* Campaign dispatch freezes eligible recipients and reserves the entire campaign budget before queuing recipients. Insufficient funding sends nobody. Consent is checked again before handoff; skipped recipients release unused reservations.
* Send and schedule requests accept approvedMaxKobo with revision; schedules additionally take sendAt. Scheduling estimates cost but reserves at dispatch. If the then-current cost exceeds the approved maximum or funding is insufficient, status becomes blocked with billingBlockReason. Review and use a fresh send action; the campaign does not automatically send late.
* MTA acceptance settles the reservation once. Cancellation and confirmed failure before handoff release unused resources. A later recipient bounce remains billable.
* An uncertain SMTP DATA/handoff outcome remains reserved until acceptance evidence is reconciled. It is not automatically released after a timeout. This prevents retries or ambiguous failures from causing duplicate sends/charges. Billing failures remain distinct from domain-health holds and recipient reputation failures.

## Alerts and refund reconciliation

* Durable, deduplicated alerts cover 80% and 100% of allowance/cap and the first prepaid usage. Existing in-app and owner-email notification settings apply.
* Payment settlements and individual partial refund events are deduplicated. A refund affecting committed funds sets reconciliationRequired and blocks live spending without creating negative prepaid debt. It does not disable Test.
* Reconciliation is an operator investigation of the payment and reservation/delivery evidence; there is no customer endpoint documented here for clearing the hold.

## Administrator rate-card contract

* GET/POST /api/v1/admin/billing/mail-rate-cards requires administrator authorization. Publish with currency: NGN, positive recipientPriceKobo and includedByPlan covering free and every active plan. The server assigns a version.
* POST /api/v1/admin/billing/mail-rate-cards/activate accepts version and confirmActivation: true. Publishing alone does not activate billing. These administrator routes are deliberately excluded from the customer SDK/OpenAPI surface. No example amount on this page is a launch price.

## Expected result

<Check>
  The summary distinguishes included allowance, reserved recipients, settled spend and Mail-only credit; no additional spending begins without owner opt-in.
</Check>

## Related guides

<CardGroup cols={2}>
  <Card title="StackShift Mail overview" href="/stackshift-mail/overview">
    Mail APIs and workflows: isolated simulation, explicit brands, consent-aware campaigns, engagement, domain health, migration, spending, inbound delivery and diagnostics.
  </Card>

  <Card title="Events, webhooks, and timelines" href="/stackshift-mail/events-webhooks-and-timelines">
    List mail events, inspect per-message timelines, subscribe webhooks, rotate secrets, retry deliveries, and verify webhook signatures.
  </Card>

  <Card title="Streams, audiences, and campaigns" href="/stackshift-mail/streams-audiences-and-campaigns">
    Separate transactional and broadcast traffic, retain consent evidence, and build private campaign drafts with unsubscribe protection.
  </Card>

  <Card title="Test environment" href="/stackshift-mail/test-environment">
    Exercise delivery, bounce, complaint and delay paths with isolated Mail data and no real email delivery.
  </Card>
</CardGroup>