Forem: Mike Hillyer

Using the SparkPost Metrics API with C#

Mike Hillyer — Mon, 16 Oct 2017 13:02:48 +0000

*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.

Using SparkPost Templates with C#

Mike Hillyer — Mon, 02 Oct 2017 13:05:01 +0000

Getting Started with C# and SparkPost

Mike Hillyer — Wed, 13 Sep 2017 13:01:58 +0000

There’s a Better Way to Send Email in C#

Sending email is a very common need for C# applications. Think about some of the use cases almost every app needs to handle: new user welcomes, event notifications, password resets, and so on. These transactional emails are workhorses, and it’s really important that they get to your users. As a C# developer, what’s the best way to get them done?

There are several C# email libraries out there, including system.net.mail, systems.web.mail. SmtpClient, MailKit, MimeKit, etc., but they all have one thing in common: you need an SMTP server to use them. Even if you have access to a server, it’s probably not tuned to ensure your messages get to your user’s inbox quickly and consistently. Using the SparkPost email delivery service is an easier way.

Let’s give it a try. Here’s how to send a message using SparkPost and C#.

Hello, World! I’m Sending Email with C# and SparkPost

The first step in sending email using C# with SparkPost is to sign up for a SparkPost developer account and get your sending domain configured. Follow our Getting Started Guide to get your account set up right with a sending domain. I’ll wait right here.

With your account set up, your sending domain configured, and your API key in hand, you’re ready to send your first email using C#. Create an application and install Sparkpost Nuget package from your Nuget Package Manager Console:

PM> Install-Package SparkPost

With SparkPost installed, we can format and send our first C# email message:

// start by creating a new SparkPost transmission
var transmission = new SparkPost.Transmission();
transmission.Content.From.Email = "me@YOURSENDINGDOMAIN.com";
transmission.Content.Subject = "Hello from SparkPost!";
transmission.Content.Text = "This is a test email.";

// add recipients who will receive your email
var recipient = new Recipient
{
    Address = new Address { Email = "you@YOUREMAILADDRESS.com" }
};
transmission.Recipients.Add(recipient);

// create a new API client using your API key
var client = new Client("<YOUR API KEY HERE>");

// if you do not understand async/await, use the sync sending mode:
client.CustomSettings.SendingMode = SendingModes.Sync;
var response = client.Transmissions.Send(transmission);

// if you understand async/await, use the default async sending mode:
// var response = client.Transmissions.Send(transmission);

// to get the transmission id back from SparkPost
// response.Result.Id;

// to get the status code of the SparkPost response
// response.Result.StatusCode;

// to get the raw json result from SparkPost
// response.Result.Content;

And that’s it! Launch the application and you should see a test message in your inbox. And the best part? You don’t have to manage any servers, monitor any services, or worry about whether the message will reach its recipient. You take care of deciding what to send and to whom, and SparkPost takes care of the rest.

Stay Tuned for More C# Email Tips

You’re well on your way to being a C# email master, thanks to one simple API. You have a working sending domain, you’ve sent your first message, and soon you will conquer the email world!

That said, your journey is not yet complete. Do you really want to have to combine content and design by building your email templates in code? Of course not! Stay tuned and I will show you how to separate the content of the message out of your API call and pre-store the message template, simplifying your code even further.

Till then, sign up for SparkPost, set up your domain, and check out our great API documentation! If you have any other questions around C# and SparkPost, come to the #csharp channel in our community slack.

This post was originally published on sparkpost.com