Mail spending controls

​

Goal

​

Prerequisites

• Keep Mail credentials on your backend. API examples use https://api.stackshift.cloud/v1 unless a public /api/v1 route is stated.

​

Workflow

​

Monthly allowance versus sending limits

​

Admin Mail pricing catalog

• Save a draft, choose a future effective time, confirm publication, then publish. Published catalogs are immutable; copy one into a new draft for subsequent changes. Concurrent changes require refreshing the draft before saving.
• GET /api/v1/admin/billing/mail-price-catalogs returns data and defaults. PUT on the same path saves id, revision, currency and plans. POST /publish requires id, revision, effectiveAt and confirmPublication: true. These routes require a live administrator session.
• Publication does not activate the older global rate-card path or enroll customers automatically. Independent Mail billing requires explicit enrollment; existing customer prices change only on eligible renewal after the required 30-day notice. Once the effective time arrives, customers can see the plans in Mail → Spending and choose enrollment.

​

Activation is explicit

• 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.

​

Choose or renew a Mail plan

• GET /api/v1/mail/billing/prices returns the currently effective published catalog. No effective catalog returns HTTP 409 mail_pricing_unavailable; network errors are shown as loading failures, not missing pricing.
• POST /api/v1/mail/billing/enroll requires confirmEnrollment: true. Paid plan review uses POST /api/v1/mail/billing/orders with plan and idempotencyKey. Quotes preserve the agreed prices and expire after 15 minutes.
• GET /api/v1/mail/billing/orders/current restores an open order or a confirmed future period. GET /orders/{orderId} reads an owned order, DELETE /orders/{orderId} cancels an unsubmitted quote, and POST /orders/{orderId}/checkout starts or resumes its payment. These order paths are relative to /api/v1/mail/billing.
• POST /api/v1/mail/billing/orders/verify accepts reference. All plan actions require a signed-in billing owner in Live mode; API tokens and Test mode cannot purchase or enroll.

​

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 the workspace has not enrolled or no effective pricing is available; existing pre-activation sending restrictions still govern live sends. Test estimates need no paid credit.

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

​

Related guides