Usage Metrics

Relevant source files

The following files were used as context for generating this wiki page:

• src/usage/usage.ts
• src/usage/usage.spec.ts
• src/usage/interfaces/index.ts
• src/emails/emails.ts
• src/emails/emails.spec.ts
• src/request-options.spec.ts

Usage Metrics track resource consumption and performance statistics across the Resend platform. This system provides real-time data on account limits, resource quotas, and detailed email performance dimensions such as delivery and open rates.

Developers use these metrics to monitor account health, verify subscription limits, and analyze campaign effectiveness. The system exposes two primary interfaces: general account usage for quota management and specialized email metrics for performance analysis.

Account Usage Monitoring

The Account Usage module retrieves current consumption levels for various Resend resources. It tracks limits and current counts for emails, contacts, segments, domains, and other platform features.

Usage Retrieval Flow

The Usage class provides a get() method that performs a GET request to the /usage endpoint. This method returns a comprehensive object detailing usage across multiple categories.

The diagram shows the request flow for retrieving account-wide usage quotas.
Sources: src/usage/usage.ts:15-20, src/usage/usage.spec.ts:18-50

Resource Quotas

The usage response categorizes consumption into specific resource types. Each resource typically includes a used count and a limit.

Resource	Monitored Fields	Reset Behavior
Emails	used, limit, sent, received	Daily and Monthly resets
Contacts	used, limit	N/A
Segments	used, limit	N/A
Domains	used, limit	N/A
Automation Runs	used, limit	Monthly resets
AI Credits	used, limit	Scheduled increases

Sources: src/usage/usage.spec.ts:19-45

Email Performance Metrics

The Email Metrics system provides granular analysis of email delivery and engagement. It allows filtering by date ranges, dimensions, and specific resource identifiers.

Filtering and Dimensions

The emails.metrics() method accepts various options to narrow down results. Dimensions like period, domain, email, and broadcast allow developers to group data for comparison.

The sequence illustrates how query parameters are constructed from options before calling the metrics endpoint.
Sources: src/emails/emails.ts:145-163, src/emails/emails.spec.ts:696-735

Query Construction

The system builds the query string by joining array values with commas and mapping camelCase options to snake_case API parameters.

Option	API Parameter	Example Value
startDate	start_date	"2026-07-01"
metrics	metrics	"sent,delivered,open_rate"
dimensions	dimensions	"period,domain"
domainId	domain_id	"uuid-123,uuid-456"

Sources: src/emails/emails.ts:166-187, src/emails/emails.spec.ts:742-772

Implementation Details

Request Handling

Usage and metrics requests support standard RequestOptions, including AbortSignal for cancellation and custom headers for tracing.

// src/usage/usage.ts
export class Usage {
  constructor(private readonly resend: Resend) {}

  async get(requestOptions: RequestOptions = {}): Promise<GetUsageResponse> {
    const data = await this.resend.get<GetUsageResponseSuccess>(
      '/usage',
      requestOptions,
    );
    return data;
  }
}

Sources: src/usage/usage.ts:12-21, src/request-options.spec.ts:193

Metric Dimensions Detail

The API supports specific identifiers to isolate performance data for different segments of the email infrastructure.

• Domain Metrics: Filtered using domainId to track reputation and delivery per verified domain.
• Email Metrics: Filtered using emailId to analyze a specific message's performance.
• Broadcast Metrics: Filtered using broadcastId to measure the impact of marketing campaigns.

Sources: src/emails/emails.ts:175-177, src/emails/emails.spec.ts:809-840

Summary

The Usage Metrics system enables comprehensive monitoring of both account resource limits and email engagement performance. By providing structured access to consumption data and granular performance dimensions, it allows for automated quota management and data-driven optimization of email delivery strategies.