Quotas

Envloped is prepaid. You can never consume email volume you have not already paid for, which means two things in practice:

• There is no invoice at the end of the month for volume you did not expect.
• When the balance runs out, the API refuses the send with 402 rather than quietly adding to a bill.

The second is the part worth designing for, and the rest of this page is about doing that well. Prices are on the pricing page; this page covers only the limits.

What you get

The free column is not something you can sign up for. Creating an account takes a payment method and starts a subscription, so every new account arrives on Transactional, Marketing, or both. The free allowance is the state that legacy and lapsed accounts are in: accounts made before signup began taking a card, and subscriptions that were cancelled or went unpaid past day 14.

For those accounts the allowance is not monthly. It is 100 emails for the lifetime of the account, and it does not reset. This is the single most common misunderstanding of this page, so the API says it in the refusal too.

Transactional and Marketing are independent. Hold either, or both — held together they share one balance, one contact store, and one sending reputation.

The campaign-send allowance scales with the contact ceiling: 15 sends per licensed contact, so raising the ceiling raises it too.

An active contact is one who is subscribed, or who opened, clicked or received a campaign in the last 30 days. Unsubscribed, bounced and dormant contacts are free to store.

One unit, counted once: recipients

Quota is measured in recipients, not requests and not API calls.

{ "to": ["a@example.com", "b@example.com", "c@example.com"], ... }

That request costs 3, exactly as three single-recipient requests would. Transactional sends, campaign sends and campaign test sends all draw on the same balance.

The balance is spent in a fixed order: included quota first, then prepaid credits, oldest pack first. Credits roll over for as long as the subscription is active.

When a send is refused

Every send path answers with 402 and a machine-readable code:

{
  "error": "Your prepaid email balance is exhausted. Top up to keep sending.",
  "code": "quota_exhausted",
  "balance": { "includedRemaining": 0, "creditBalance": 0, "freeRemaining": 0 },
  "top_up_url": "https://envloped.com/settings/billing"
}

Branch on code. The message is prose and may be reworded; the codes are API surface and are added to, never renamed.

A campaign launch that cannot be afforded is refused before any recipient row is written, and its 402 carries an extra shortfall — how many more recipients the account would need. A campaign already draining that runs out pauses at paused_billing and resumes when the balance does; nothing is double-sent and nothing is lost.

Never retry a 402

A 429 clears by waiting. A 402 clears only when money moves — retrying the same request will fail identically until it does. If your client has one retry policy for "server said no", make sure 402 is not in it.

Both SDKs and the CLI enforce this — the CLI in particular never retries a 402, where it does retry 429 and 5xx.

import { isPaymentRequiredError } from '@envloped/envloped-js';

try {
  await envloped.emails.send({ from, to, subject, html });
} catch (error) {
  if (isPaymentRequiredError(error)) {
    switch (error.code) {
      case 'free_quota_exhausted':
        return promptToSubscribe(error.topUpUrl);
      case 'quota_exhausted':
        return promptToTopUp(error.balance);
      default:
        return alertAnOperator(error); // a card or lifecycle problem
    }
  }
  throw error;
}

_, err := client.Emails.Send(req)
if errors.Is(err, envloped.ErrPaymentRequired) {
    var pre *envloped.PaymentRequiredError
    errors.As(err, &pre)

    switch pre.Code {
    case "free_quota_exhausted":
        return promptToSubscribe(pre.TopUpURL)
    case "quota_exhausted":
        return promptToTopUp(pre.Balance)
    default:
        return alertAnOperator(pre)
    }
}

$ envloped send --from you@yourdomain.com --to user@example.com \
    --subject "Hello" --text "Hi"
API error (402): Your prepaid email balance is exhausted. [quota_exhausted]
Hint: 0 emails left. Buy a pack or enable auto-recharge at https://envloped.com/settings/billing

Auto-recharge

Auto-recharge buys a pack automatically when the balance runs out, so a send that would have been refused goes through instead. It is off unless you turn it on, and it has a ceiling per billing period that you set — nothing is ever bought above it.

Two behaviours worth knowing:

• It fires only on quota_exhausted. It will not fire on a legacy free account (that would turn a lapsed account into a purchase without anyone deciding to) and not on a blocked account.
• A declined charge switches it off and emails you. The next send then gets a clean 402 rather than a card retry per message.

Contacts above your ceiling

The marketing product licenses a number of active contacts. A daily job counts them; crossing the ceiling raises it, and the difference is billed immediately.

Contacts above the paid ceiling can still be created, imported and stored — they are only excluded from campaign audiences until the charge lands. An import of 40,000 contacts onto a 5,000-contact ceiling never fails; the new contacts become mailable after the next daily count.

If a payment fails

Paying at any point before day 14 restores everything immediately: sending resumes, paused campaigns unpause, and credits are untouched throughout.

Legacy plans

Accounts on a plan that predates this model keep it, with no end date and no migration. They are not gated on a prepaid balance, and nothing on this page applies to them — their billing page shows the metered view that matches their invoice.