Initial push of Plunk Next

2025-12-01 09:56:56 +01:00
parent 07cea20262
commit ff1876d580
566 changed files with 89036 additions and 28423 deletions
@@ -0,0 +1,115 @@
+---
+title: Billing & Usage Limits
+description: Control monthly email usage and costs
+---
+
+## What are billing limits
+
+Billing limits let you cap monthly email sends by category to control costs. Set maximum emails per month for transactional, campaigns, and workflows separately.
+
+## Email categories
+
+Plunk tracks usage across three categories:
+
+**Transactional** — Emails sent via `/v1/send` API
+- Order confirmations, password resets
+- Account notifications
+- Any direct API sends
+
+**Campaigns** — One-time broadcast emails
+- Newsletters, announcements
+- Promotional campaigns
+- Marketing blasts
+
+**Workflows** — Automated sequence emails
+- Onboarding flows
+- Drip campaigns
+- Behavior-triggered emails
+
+**Note:** The category is determined by how you send (API, campaign, or workflow), not the template type.
+
+## How limits work
+
+### Monthly reset
+
+Usage resets on the 1st of each month (UTC). Starts fresh at 0.
+
+### Enforcement
+
+When sending emails:
+
+- **Under 80%** — Sends normally
+- **80-99%** — Sends with warning flag
+- **100%+** — Blocked with 429 error
+
+### Unlimited
+
+Set limit to unlimited for any category (default for all categories).
+
+## Manage limits
+
+You can view and update your billing limits in the dashboard:
+
+1. Go to **Settings** → **Billing**
+2. View current usage for each category
+3. Update limits as needed (requires Admin or Owner role)
+
+## When limit is reached
+
+### API error
+
+```json
+{
+  "code": 429,
+  "error": "Too Many Requests",
+  "message": "Monthly limit exceeded for campaigns (50000/50000). Resets on 2025-12-01."
+}
+```
+
+### Handle in code
+
+```javascript
+try {
+  const response = await fetch('{{API_URL}}/v1/send', {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${apiKey}`,
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify(emailData)
+  });
+
+  if (response.status === 429) {
+    const error = await response.json();
+
+    // Option 1: Notify admin
+    await notifyAdmin(`Limit reached: ${error.message}`);
+
+    // Option 2: Increase limit
+    await increaseBillingLimit('transactional', 200000);
+
+    // Option 3: Queue for next month
+    await queueForNextMonth(emailData);
+  }
+} catch (error) {
+  console.error('Send failed:', error);
+}
+```
+
+## Best practices
+
+**Monitor usage regularly** — Check dashboard weekly to avoid surprises.
+
+**Set alerts** — Configure notifications at 80% usage.
+
+**Plan for growth** — Increase limits before campaigns, not during.
+
+**Use categories wisely** — Critical transactional emails might need higher limits.
+
+**Review monthly** — Adjust limits based on actual usage patterns.
+
+## Next Steps
+
+- [Track usage analytics](/guides/analytics)
+- [Scale email delivery](/guides/scaling-email)
+- [Troubleshooting limits](/guides/troubleshooting)