Skip to content
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 60 additions & 0 deletions src/Resend/EmailMetrics.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
using System.Text.Json.Serialization;

namespace Resend;

/// <summary>
/// Email metrics for a given reporting period.
/// </summary>
/// <see href="https://resend.com/docs/api-reference/emails/get-metrics"/>
public class EmailMetrics
{
/// <summary />
[JsonPropertyName( "object" )]
public string Object { get; set; } = default!;

/// <summary>
/// Start of the reporting period.
/// </summary>
[JsonPropertyName( "start_date" )]
[JsonConverter( typeof( JsonUtcDateTimeConverter ) )]
public DateTime StartDate { get; set; }

/// <summary>
/// End of the reporting period.
/// </summary>
[JsonPropertyName( "end_date" )]
[JsonConverter( typeof( JsonUtcDateTimeConverter ) )]
public DateTime EndDate { get; set; }

/// <summary>
/// Metrics included in this response.
/// </summary>
[JsonPropertyName( "metrics" )]
public List<MetricType> Metrics { get; set; } = default!;

/// <summary>
/// Dimensions this response is broken down by.
/// </summary>
[JsonPropertyName( "dimensions" )]
public List<MetricDimension> Dimensions { get; set; } = default!;

/// <summary>
/// Bucket size used for the <see cref="MetricDimension.Period"/> dimension.
/// </summary>
[JsonPropertyName( "granularity" )]
public MetricsGranularity Granularity { get; set; }

/// <summary>
/// Totals for the whole reporting period, one entry per requested metric.
/// </summary>
[JsonPropertyName( "totals" )]
public Dictionary<string, double> Totals { get; set; } = default!;

/// <summary>
/// One row per combination of the requested dimensions. Absent when no dimensions
/// were requested -- in that case only <see cref="Totals"/> is populated.
/// </summary>
[JsonPropertyName( "data" )]
[JsonIgnore( Condition = JsonIgnoreCondition.WhenWritingNull )]
public List<EmailMetricsDataPoint>? Data { get; set; }
}
56 changes: 56 additions & 0 deletions src/Resend/EmailMetricsDataPoint.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
using System.Text.Json;
using System.Text.Json.Serialization;

namespace Resend;

/// <summary>
/// One row of <see cref="EmailMetrics.Data"/>. Which dimension fields are populated depends on
/// the dimensions requested via <see cref="EmailMetricsQuery.Dimensions"/>.
/// </summary>
public class EmailMetricsDataPoint
{
/// <summary>
/// Time bucket this row covers, present when <see cref="MetricDimension.Period"/> was requested.
/// </summary>
[JsonPropertyName( "period" )]
public string? Period { get; set; }

/// <summary>
/// Sending domain identifier, present when <see cref="MetricDimension.Domain"/> was requested.
/// </summary>
[JsonPropertyName( "domain_id" )]
public Guid? DomainId { get; set; }

/// <summary>
/// Sending domain name, present when <see cref="MetricDimension.Domain"/> was requested.
/// </summary>
[JsonPropertyName( "domain_name" )]
public string? DomainName { get; set; }

/// <summary>
/// Email identifier, present when <see cref="MetricDimension.Email"/> was requested.
/// </summary>
[JsonPropertyName( "email_id" )]
public Guid? EmailId { get; set; }

/// <summary>
/// Broadcast identifier, present when <see cref="MetricDimension.Broadcast"/> was requested.
/// </summary>
[JsonPropertyName( "broadcast_id" )]
public Guid? BroadcastId { get; set; }

/// <summary>
/// Broadcast display name, present when <see cref="MetricDimension.Broadcast"/> was requested.
/// </summary>
[JsonPropertyName( "broadcast_name" )]
public string? BroadcastName { get; set; }

/// <summary>
/// Metric values for this row, keyed by metric name (for example <c>delivered</c>,
/// <c>opened</c>) -- the API returns these as sibling fields of the dimension keys above,
/// rather than nested under their own key, and the set present depends on the requested
/// <see cref="EmailMetricsQuery.Metrics"/>.
/// </summary>
[JsonExtensionData]
public Dictionary<string, JsonElement> MetricValues { get; set; } = new();
}
67 changes: 67 additions & 0 deletions src/Resend/EmailMetricsQuery.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
namespace Resend;

/// <summary>
/// Query parameters for <see cref="IResend.EmailMetricsAsync"/>.
/// </summary>
public class EmailMetricsQuery
{
/// <summary>
/// Start of the reporting period. Defaults server-side to 6 days before <see cref="EndDate"/>.
/// </summary>
public DateTime? StartDate { get; set; }

/// <summary>
/// End of the reporting period. Defaults server-side to now.
/// </summary>
public DateTime? EndDate { get; set; }

/// <summary>
/// IANA timezone (for example <c>America/New_York</c>) used to bucket results. Defaults
/// server-side to <c>UTC</c>.
/// </summary>
public string? Timezone { get; set; }

/// <summary>
/// Bucket size used when <see cref="MetricDimension.Period"/> is one of <see cref="Dimensions"/>.
/// Defaults server-side to <see cref="MetricsGranularity.Daily"/>.
/// </summary>
public MetricsGranularity? Granularity { get; set; }

/// <summary>
/// Metrics to include in the response. Defaults server-side to all metrics.
/// </summary>
public List<MetricType>? Metrics { get; set; }

/// <summary>
/// Dimensions to break the results down by. Defaults server-side to none, in which case
/// the response carries only <see cref="EmailMetrics.Totals"/>, no <see cref="EmailMetrics.Data"/>.
/// </summary>
/// <remarks>
/// <see cref="MetricDimension.Email"/> cannot be combined with <see cref="MetricDimension.Broadcast"/>
/// -- the API rejects that combination with a validation error.
/// </remarks>
public List<MetricDimension>? Dimensions { get; set; }

/// <summary>
/// Restrict results to these sending domains. Maximum 100.
/// </summary>
public List<Guid>? DomainId { get; set; }

/// <summary>
/// Restrict results to these emails. Maximum 100.
/// </summary>
/// <remarks>
/// Cannot be combined with the <see cref="MetricDimension.Broadcast"/> dimension or
/// with <see cref="BroadcastId"/>.
/// </remarks>
public List<Guid>? EmailId { get; set; }

/// <summary>
/// Restrict results to these broadcasts. Maximum 100.
/// </summary>
/// <remarks>
/// Cannot be combined with the <see cref="MetricDimension.Email"/> dimension or
/// with <see cref="EmailId"/>.
/// </remarks>
public List<Guid>? BroadcastId { get; set; }
}
16 changes: 16 additions & 0 deletions src/Resend/IResend.cs
Original file line number Diff line number Diff line change
Expand Up @@ -190,6 +190,22 @@ public interface IResend
/// <see href="https://www.resend.com/docs/api-reference/emails/share-email"/>
Task<ResendResponse<EmailShareResult>> EmailShareAsync( Guid emailId, string? expiresIn = null, CancellationToken cancellationToken = default );

/// <summary>
/// Retrieves aggregate email metrics (delivery, engagement, bounce, etc.) for a reporting
/// period, optionally broken down by one or more dimensions.
/// </summary>
/// <param name="query">
/// Metrics query.
/// </param>
/// <param name="cancellationToken">
/// Cancellation token.
/// </param>
/// <returns>
/// Email metrics.
/// </returns>
/// <see href="https://resend.com/docs/api-reference/emails/get-metrics"/>
Task<ResendResponse<EmailMetrics>> EmailMetricsAsync( EmailMetricsQuery? query = null, CancellationToken cancellationToken = default );

/// <summary>
/// Lists email attachments from a sent email.
/// </summary>
Expand Down
38 changes: 38 additions & 0 deletions src/Resend/MetricDimension.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
using System.Text.Json.Serialization;

namespace Resend;

/// <summary>
/// A dimension by which email metrics can be broken down.
/// </summary>
/// <remarks>
/// <see cref="Email"/> cannot be combined with <see cref="Broadcast"/> -- the API rejects
/// that combination with a validation error.
/// </remarks>
[JsonConverter( typeof( JsonStringEnumValueConverter<MetricDimension> ) )]
public enum MetricDimension
{
/// <summary>
/// Break down results into time buckets, sized per the requested granularity.
/// </summary>
[JsonStringValue( "period" )]
Period = 1,

/// <summary>
/// Break down results by sending domain.
/// </summary>
[JsonStringValue( "domain" )]
Domain,

/// <summary>
/// Break down results by individual email.
/// </summary>
[JsonStringValue( "email" )]
Email,

/// <summary>
/// Break down results by broadcast.
/// </summary>
[JsonStringValue( "broadcast" )]
Broadcast,
}
142 changes: 142 additions & 0 deletions src/Resend/MetricType.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
using System.Text.Json.Serialization;

namespace Resend;

/// <summary>
/// A metric that can be requested from <see cref="IResend.EmailMetricsAsync"/>.
/// </summary>
[JsonConverter( typeof( JsonStringEnumValueConverter<MetricType> ) )]
public enum MetricType
{
/// <summary>
/// Number of emails received/accepted for sending.
/// </summary>
[JsonStringValue( "received" )]
Received = 1,

/// <summary>
/// Number of emails delivered to the recipient's mail server.
/// </summary>
[JsonStringValue( "delivered" )]
Delivered,

/// <summary>
/// Number of emails the recipient marked as spam.
/// </summary>
[JsonStringValue( "complained" )]
Complained,

/// <summary>
/// Number of emails suppressed instead of being sent.
/// </summary>
[JsonStringValue( "suppressed" )]
Suppressed,

/// <summary>
/// Number of emails that bounced, of any kind.
/// </summary>
[JsonStringValue( "bounced" )]
Bounced,

/// <summary>
/// Number of emails that bounced transiently (may succeed on retry).
/// </summary>
[JsonStringValue( "bounced_transient" )]
BouncedTransient,

/// <summary>
/// Number of emails that bounced permanently.
/// </summary>
[JsonStringValue( "bounced_permanent" )]
BouncedPermanent,

/// <summary>
/// Number of emails that bounced for an undetermined reason.
/// </summary>
[JsonStringValue( "bounced_undetermined" )]
BouncedUndetermined,

/// <summary>
/// Number of emails opened by the recipient.
/// </summary>
[JsonStringValue( "opened" )]
Opened,

/// <summary>
/// Number of emails whose links were clicked by the recipient.
/// </summary>
[JsonStringValue( "clicked" )]
Clicked,

/// <summary>
/// Number of recipients who unsubscribed.
/// </summary>
[JsonStringValue( "unsubscribed" )]
Unsubscribed,

/// <summary>
/// Number of emails whose delivery was delayed.
/// </summary>
[JsonStringValue( "delivery_delayed" )]
DeliveryDelayed,

/// <summary>
/// Number of emails that failed to send.
/// </summary>
[JsonStringValue( "failed" )]
Failed,

/// <summary>
/// Number of emails sent.
/// </summary>
[JsonStringValue( "sent" )]
Sent,

/// <summary>
/// Number of unique recipients who opened an email.
/// </summary>
[JsonStringValue( "unique_opened" )]
UniqueOpened,

/// <summary>
/// Number of unique recipients who clicked a link.
/// </summary>
[JsonStringValue( "unique_clicked" )]
UniqueClicked,

/// <summary>
/// Delivered / sent, as a fraction.
/// </summary>
[JsonStringValue( "delivery_rate" )]
DeliveryRate,

/// <summary>
/// Unique opens / delivered, as a fraction.
/// </summary>
[JsonStringValue( "open_rate" )]
OpenRate,

/// <summary>
/// Unique clicks / delivered, as a fraction.
/// </summary>
[JsonStringValue( "click_rate" )]
ClickRate,

/// <summary>
/// Bounced / sent, as a fraction.
/// </summary>
[JsonStringValue( "bounce_rate" )]
BounceRate,

/// <summary>
/// Complained / delivered, as a fraction.
/// </summary>
[JsonStringValue( "complaint_rate" )]
ComplaintRate,

/// <summary>
/// Unsubscribed / delivered, as a fraction.
/// </summary>
[JsonStringValue( "unsubscribe_rate" )]
UnsubscribeRate,
}
Loading
Loading