Plan Limits

Every API call respects the same plan limits as the dashboard UI. Limits are enforced before the operation is performed — exceeding a quota or accessing a gated feature returns an error immediately. There is no silent over-delivery.

Plans

Email Send Quotas

Feature Quotas

Feature Flags

Some features are binary — either enabled or disabled for the plan, regardless of count.

How Plan Limits Are Enforced

When an API key makes a request, the server resolves the key → user → active subscription → plan chain:

msk_xxx  →  user_id  →  user_subscriptions (status: active|trialing)
                     →  subscription_plans (quotas + feature flags)

Two enforcement paths:

1. Feature checks (checkPlanLimit RPC) — for creating resources (contacts, campaigns, templates, etc.). Returns 403 if the user is at or over their plan's limit.

2. Atomic send quota (check_and_increment_email_usage RPC) — for POST /v1/send. Atomically checks and increments the daily and monthly send counter in a single DB transaction to prevent TOCTOU races under concurrent sends. Returns 429 if either limit is reached.

Overage Billing

When Allow Overage is enabled in Settings → Billing, usage beyond the plan limit is billed at the end of the billing cycle instead of being blocked. Overage is opt-in and disabled by default.

When overage is disabled (default), requests that exceed the limit are rejected with 429 and no partial work is done.

Checking Current Usage

GET /api/v1/usage

Returns the current period's usage against plan limits. Requires session auth or an API key with the read scope.

curl https://api.misar.io/mail/v1/usage \
  -H "Authorization: Bearer msk_YOUR_API_KEY"

Response

{
  "success": true,
  "plan": "pro",
  "billing_period": {
    "start": "2026-04-01T00:00:00Z",
    "end":   "2026-04-30T23:59:59Z"
  },
  "usage": {
    "emails_sent_today":     1240,
    "emails_sent_month":     18400,
    "contacts":              3102,
    "campaigns":             7,
    "automations":           3,
    "ai_generations":        44,
    "email_validations":     210,
    "custom_domains":        2,
    "dedicated_ips":         0
  },
  "limits": {
    "emails_per_day":        10000,
    "emails_per_month":      300000,
    "contacts":              null,
    "campaigns":             null,
    "automations":           20,
    "ai_generations":        100,
    "email_validations":     1000,
    "custom_domains":        null,
    "dedicated_ips":         0
  },
  "features": {
    "bulk_import":           true,
    "ai_features":           true,
    "custom_smtp":           false
  },
  "overage_enabled": false
}

null in limits means unlimited for the current plan.

Limit Enforcement Error Responses

403 — Feature limit reached (resource quota)

{
  "success":       false,
  "error":         "Automation limit reached (20 / 20). Upgrade to Max for unlimited automations.",
  "feature":       "automations",
  "current":       20,
  "limit":         20,
  "required_plan": "max"
}

429 — Send quota exceeded

{
  "success":      false,
  "error":        "Send limit reached. Upgrade at mail.misar.io/pricing",
  "feature":      "emails_per_month",
  "current":      300000,
  "limit":        300000,
  "retry_after":  "2026-05-01T00:00:00Z"
}

Upgrading

Visit mail.misar.io/pricing to upgrade. Changes take effect immediately at the API layer — no key rotation needed.