API Reference
Usage
Check your email sending usage, limits, and daily statistics programmatically. Monitor your account to stay within rate limits.
Emails Sent
Track monthly volume
Delivery Rate
Monitor success rates
Daily Stats
Historical breakdown
Rate Limits
Plan-based limits
GET
/v1/usageGet Usage Statistics
Retrieve your current usage statistics including emails sent, delivery rates, and rate limits for the current billing period.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
period | string | Time period for daily stats: 7d, 30d, 90d. Default: 30d |
Request
cURL
curl https://www.unosend.co/api/v1/usage?period=30d \
-H "Authorization: Bearer un_your_api_key"Response
200 OK
{
"success": true,
"data": {
"plan": "starter",
"rate_limit": {
"requests_per_second": 50,
"burst_limit": 100
},
"usage": {
"emails_sent": 2847,
"emails_limit": 50000,
"emails_delivered": 2801,
"emails_bounced": 23,
"period_start": "2024-12-01T00:00:00.000Z",
"period_end": "2024-12-31T00:00:00.000Z"
},
"daily_stats": {
"today": 156,
"peak": 423,
"average": 95,
"history": [
{ "date": "2024-12-01", "count": 89 },
{ "date": "2024-12-02", "count": 156 },
{ "date": "2024-12-03", "count": 423 }
]
}
}
}Response Fields
| Field | Type | Description |
|---|---|---|
plan | string | Current plan (free, starter, pro, growth, scale, enterprise) |
rate_limit.requests_per_second | number | Maximum requests per second for your plan |
rate_limit.burst_limit | number | Maximum burst requests allowed |
usage.emails_sent | number | Total emails sent this billing period |
usage.emails_limit | number | Maximum emails allowed for your plan |
usage.emails_delivered | number | Successfully delivered emails |
usage.emails_bounced | number | Bounced or failed emails |
daily_stats.today | number | Emails sent today |
daily_stats.peak | number | Highest daily count in the period |
daily_stats.average | number | Average daily count in the period |
daily_stats.history | array | Daily breakdown with date and count |
Common Use Cases
Check if approaching limit
cURL
# Get usage and check percentage used
curl https://www.unosend.co/api/v1/usage \
-H "Authorization: Bearer un_your_api_key" | \
jq '.data.usage | (.emails_sent / .emails_limit * 100) | floor'Get last 7 days stats
cURL
curl "https://www.unosend.co/api/v1/usage?period=7d" \
-H "Authorization: Bearer un_your_api_key"Monitor delivery rate
cURL
# Calculate delivery rate percentage
curl https://www.unosend.co/api/v1/usage \
-H "Authorization: Bearer un_your_api_key" | \
jq '.data.usage | (.emails_delivered / .emails_sent * 100) | floor'Rate Limits by Plan
| Plan | Requests/Second | Burst Limit |
|---|---|---|
| Free | 10 | 20 |
| Starter | 50 | 100 |
| Pro | 100 | 200 |
| Growth | 200 | 500 |
| Scale | 500 | 1,000 |
| Enterprise | 1,000 | 2,000 |