Usage & Billing API
Relevant source files
The following files were used as context for generating this wiki page:
The Usage & Billing API provides programmatic access to account consumption metrics and resource limits. It allows you to monitor your volume of sent and received emails, active contacts, segments, domains, and automation runs. This service enables developers to track quota usage and respond to rate limits within their applications.
Usage Service Overview
The Usage service is accessed through the main Resend client. It exposes methods to retrieve a comprehensive usage object containing current consumption data and maximum permitted limits across multiple Resend features.
The diagram shows the relationship between the main Resend client and the Usage service interface.
Sources: resend.go, usage.go:50-60
Data Models
The API returns a Usage struct representing the current state of account resources. Metrics are categorized by resource type, with most resources including fields for Used and Limit.
Email Usage Metrics
Email tracking is split into daily and monthly windows. Both windows include counts for sent and received emails, as well as a reset timestamp.
| Field | Type | Description |
|---|---|---|
Used | int | Total number of emails processed (Sent + Received) |
Limit | *int | Maximum allowed emails for the period (null if unlimited) |
Sent | int | Total number of emails successfully sent |
Received | int | Total number of emails received |
ResetsAt | string | ISO 8601 timestamp when the usage window resets |
Sources: usage.go:17-30, usage_test.go:27-35
Resource Quotas
In addition to email volume, the API tracks the count and limits for architectural resources.
| Resource | Field | Type | Description |
|---|---|---|---|
| Contacts | Used, Limit | int | Total stored contacts vs allowed capacity |
| Segments | Used, Limit | int/ptr | Defined contact segments |
| Domains | Used, Limit | int/ptr | Verified sending domains |
| Automations | Used, Limit | int | Total automation runs vs limit |
Sources: usage.go:34-42, usage_test.go:39-55
Retrieving Usage Information
You retrieve usage data using the Get() or GetWithContext() methods. The following sequence describes the request flow from the SDK to the Resend API.
The sequence diagram illustrates the synchronous flow for fetching account consumption data.
Sources: usage.go:62-85, usage_test.go:15-25
Rate Limit Configuration
The Usage response includes a RateLimit field. This defines the current API throughput constraints for your account.
- Limit: The maximum number of requests allowed.
- Duration: The time window for the limit (e.g., "1000ms").
Sources: usage.go:44-48, usage_test.go:56-58
Implementation Example
The following example demonstrates how to check if an account is approaching its monthly email limit.
usage, err := client.Usage.Get()
if err != nil {
panic(err)
}
if usage.Emails.Monthly.Limit != nil {
limit := *usage.Emails.Monthly.Limit
used := usage.Emails.Monthly.Used
fmt.Printf("Monthly Usage: %d/%d emails\n", used, limit)
}
Sources: usage_test.go:40-45, usage.go:21-25
Summary
The Usage & Billing API is a read-only service that provides transparency into account activity. By monitoring these metrics, you can automate alerts for quota exhaustion or dynamically adjust sending volume based on daily and monthly resets. The service covers all core Resend primitives, including emails, contacts, segments, and domains.
Sources: usage.go, usage_test.go