Email Metrics & Logs
Relevant source files
The following files were used as context for generating this wiki page:
The Email Metrics & Logs system provides programmatic access to delivery statistics and event-based tracking for outbound and inbound communications. It tracks performance indicators such as delivery rates, open rates, and click-through rates while maintaining detailed records of email events for auditing and monitoring.
This module allows you to retrieve aggregated data across specific timeframes and dimensions (e.g., domain, email, or broadcast) and observe real-time status updates through HTTP response headers and webhook events.
Email Metrics API
The Emails.metrics() method retrieves statistical data for sent emails. The system aggregates these metrics based on specified granularities and dimensions.
Metrics Dimensions and Granularity
You can bucket results using different time intervals and break them down by specific identifiers.
| Parameter | Type | Description |
|---|---|---|
granularity | MetricsGranularity | The bucket size: "hourly", "daily", "weekly", "monthly". |
dimensions | List[MetricsDimension] | Breakdown criteria: "period", "domain", "email", "broadcast". |
start_date | str | Start of date range (ISO 8601). Defaults to 6 days before end date. |
end_date | str | End of date range (ISO 8601). Defaults to now. |
Sources: resend/emails/_emails.py:165-188
Available Metrics
The system calculates various performance and status metrics:
- Volume Metrics:
sent,delivered,received. - Engagement Metrics:
opened,clicked,unique_opened,unique_clicked. - Negative Signals:
bounced,complained,suppressed,unsubscribed. - Rate Metrics:
delivery_rate,open_rate,click_rate,bounce_rate.
Sources: resend/emails/_emails.py:27-50
Metrics Request Flow
The SDK validates parameters locally before performing a GET request to the /emails/metrics endpoint.
Note: The system prohibits combining the "email" dimension/filter with the "broadcast" dimension/filter.
Sources: resend/emails/_emails.py:236-249, resend/emails/_emails.py:537-550
Event Logging and Webhooks
Logging behavior is captured through real-time webhook events and individual email status updates. Every sent or received email generates an event trail that the API exposes.
Webhook Event Types
Webhooks provide a push-based logging mechanism. The system emits specific payloads for the following email events:
| Event Type | Data Payload Class | Description |
|---|---|---|
email.sent | BaseEmailEventData | Email created and queued for delivery. |
email.delivered | BaseEmailEventData | Successfully accepted by receiving server. |
email.bounced | EmailBouncedEventData | Permanent or temporary delivery failure. |
email.opened | BaseEmailEventData | Recipient viewed the email content. |
email.clicked | EmailClickedEventData | Recipient engaged with a link. |
Sources: resend/webhooks/_webhook_event.py:461-512
Detailed Event Schemas
Events like bounces and clicks contain specialized metadata for diagnostic purposes.
Metadata and HTTP Headers
The SDK facilitates log monitoring by injecting HTTP-level metadata into response objects. This allows you to track infrastructure limits and request identifiers without separate API calls.
Header Categories
| Category | Field Name | Purpose |
|---|---|---|
| SDK Metadata | http_headers | Contains x-request-id, ratelimit-limit, and ratelimit-remaining. |
| Inbound MIME | headers | Original MIME headers (e.g., X-Mailer) from received emails. |
| Outbound Custom | headers | User-defined headers (e.g., X-Entity-Ref-ID) sent with an email. |
Sources: examples/with_headers.py:10-22, tests/emails_test.py:657-673
Rate Limit Tracking Implementation
You can monitor rate limits by accessing the http_headers key within the SendResponse or ReceivedEmail objects.
# Example of tracking usage from response metadata
response = resend.Emails.send(params)
http_meta = response.get("http_headers", {})
remaining = http_meta.get("ratelimit-remaining")
limit = http_meta.get("ratelimit-limit")
if remaining and limit:
print(f"Usage: {int(limit) - int(remaining)}/{limit}")
Sources: examples/with_headers.py:68-79
Implementation Summary
The Email Metrics & Logs features allow for both proactive performance analysis and reactive troubleshooting. Metrics provide high-level trends through the /emails/metrics endpoint, while Logs are maintained via individual email retrieval, webhook event payloads, and HTTP header metadata.
Sources: resend/emails/_emails.py:537-550, resend/webhooks/_webhook_event.py:112-160, examples/emails_metrics.py:1-20