116 lines
2.7 KiB
Plaintext
116 lines
2.7 KiB
Plaintext
---
|
|
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)
|