Using the SparkPost Metrics API with C#

*Today’s blog is written by Darren Cauthon, community member and original author of the SparkPost C# Library. Thanks for the post, Darren! We hope you enjoy.

How to Use the SparkPost Metrics API with C

In our first two tutorials on using SparkPost with C#, we learned how to send an email from a C# application and how to manipulate email templates using C# code. You’ll want to start there to get the SparkPost C# library installed via NuGet, it’s all good stuff.

But most of the time when you send an email from your app, you’ll also want to know what happened to that message: was it delivered? Did your user open it or even click on link in the message body? Visibility into message disposition and performance is crucial for many apps.

That’s why the SparkPost C# library includes methods for getting important metrics about the emails that you send. Today, we’re going to look at how they work.

There are two mechanisms for getting these analytics: pushing and pulling. With pushing (via a webhook), you can get your metrics streamed in near real-time as SparkPost posts the information to a web endpoint that you provide. A future tutorial will provide some help on setting up a webhook endpoint in a standard .Net MVC application.

Today, however, we’ll focus on pull-style API-based queries for your metrics via the C# wrapper. You can query the SparkPost API for just about any type of information you’d want about the emails you send within the past few weeks, and the API will return the information you requested.

This tutorial will also provide some insight into the library’s design, and how you can use it for other SparkPost API calls you’d want to make.

A SparkPost Metrics API Quick Start

When using the C# SparkPost library, the first place to check is the SparkPost API documentation. The C# library was written to mirror the SparkPost web API as closely as possible. Naturally, the API docs include specific information about metrics. Look there to see what sorts of metrics you might want to gather.

Let’s try the first method in the docs: Gathering metrics by domain. Let’s build a sample request that will return the number of accepted and bounced emails that were sent to Gmail or Yahoo Mail. Here is C# code that will return your results.

var client = new Client("YOUR API KEY");
client.CustomSettings.SendingMode = SendingModes.Sync; 

var query = new MetricsQuery {
    From = DateTime.Now.AddDays(-7),
    Metrics = new[] { "count_accepted", "count_bounce" },
    Domains = new[] { "gmail.com", "yahoo.com" },
};

var response = await client.Metrics.GetDeliverabilityByDomain(query);

Here are your results:

It’s really that easy. All of the metrics data you want, for this and any of the other API metric methods, will be returned in this form. The only real question is what data you want, so check out the SparkPost API documentation and make the query you want!

How to Keep the SparkPost C# Library Up-To-Date with API Changes

One of the difficulties in using a library for a service like SparkPost is keeping up-to-date with changes. SparkPost is always adding new features to its API, but are those new features reflected in the library? Sometimes there is a lag between when API developers add features and when library authors add support.

The C# library tries to mitigate those issues by allowing you to extend the library, yourself. The example above showed how to use the MetricsQuery, but you can pass any object to use as a query—so long as it matches the style and naming of the SparkPost service.

Here is a concrete example: SparkPost developers added a new API feature, the ability to pass a “limit to limit the size of your result. That feature was not available when the MetricsQuery class was written, so it does not have Limit available. So does that mean you can’t use Limit in C#? No, that’s still available to you – just have to pass it yourself. Like with an anonymous object:

var client = new Client("YOUR API KEY");
client.CustomSettings.SendingMode = SendingModes.Sync; 

var response = client.Metrics.GetDeliverabilityByDomain(new {
  From = DateTime.Now.AddDays(-0),
  Metrics = "count_accepted,count_bounce",
  Domains = "gmail.com,yahoo.com",
  Limit = 10
});

Another method would be to extend the MetricsQuery and add an “int Limit { get; set; } property. But the main point to notice is that so long as you stay consistent with the SparkPost documentation and naming, this library can extend itself.

The SparkPost C# Library Is Open Source

I’m the original author of the SparkPost library, but there are more than a dozen developers who have contributed code to this library, like this Metrics library, which was contributed by Aaron Sherber. Each developer on this library was either a SparkPost employee or a customer of SparkPost, all of us with an interest in making this library work well.

As the SparkPost API expands, this library will expand with it. And we’re accepting contributions from anybody who wants to help!

The post Using the SparkPost Metrics API with C# appeared first on SparkPost.