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

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:

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!

— Darren Cauthon

Any questions for us? Give us a shout on Twitter or in our community slack channel, we’d love to talk C#, Metrics, APIs – whatever’s on your mind.

Transform your New User Welcome emails with C# and SparkPost Click to Tweet
If you take a look at the workhorse transactional email in your inbox—things like receipts, shipping notices, password resets, and the like — I bet you’ll notice there’s an awful lot of ugly emails. A company will spend time and money on a brand, on designing a compelling website, and on advertising, but when it’s time for their automated systems to send an email to the user, you get something like this:

All that work, and it’s thrown away on a plain-text email with no design at all. Why? Because design and code don’t mix well together. Most automated messages are built line by line in plain text and then sent using a .Send() function. Marketers don’t like it because they can’t update the look and feel of the messages to match the rest of their work and developers don’t like it because it clutters their code. They also end up getting constantly asked to change a line here, a word there, etc.

There is a better way. SparkPost’s built-in templating capabilities allow for a separation of design and code. Instead of trying to embed the content of your messages into your code, you can simply and easily upload your templates to SparkPost and call our APIs with a template reference rather than passing the formatted message content. Not only is this easier than techniques such as parsing Razer pages to strings, but it also moves the template out of the application completely, leaving the developer to focus on code.

Let’s get started!

Sending a Template Email Through SparkPost with C#

If you’re following along at home, we started with a quick example of how to send a C# email using the SparkPost API (and if you’re not, read it now to see how easy it is to send a C# email message using SparkPost, I’ll wait). Our next goal is to remove the message design elements from our code and replace them with a stored template.

First, we need to create and store a template. Start by reading our guide to managing templates and set up a template. For this example, I’ll use the following HTML template in a template named “My First Email”:

The SparkPost templating language is based on HandleBars and is straightforward to use. In this case, substitutions occur inside the {{ }} blocks, and SparkPost templating supports logic, basic operations, and even looping through arrays. For more information, see the Substitutions Reference in our API Documentation.

Once our template is stored and published, we can use it in a call to the transmissions API:

And that’s it. We create a transmission, create a recipient, add template substitution data to the recipient, add the recipient to the transmission, and send the transmission to the SparkPost API. If you wanted to send to more than one recipient, you would simply add more recipients to the transmission before sending.

Your code is focused on triggering the message and filling in the blanks, the design is completely separated out and not a concern. Is it less ugly than the example that I started with? Well, no (I’m no designer), but at least now your design team can log into the SparkPost web UI and make it prettier without asking you to change code to improve the design!

Next up on your journey

You’ve taken the next step to being a C# email master by separating design from sending logic. You have a working template, you’ve sent it in a message, and your design team can adjust the look and feel of the message without your involvement!

Once again, your journey is not yet complete. Is it enough to send a message, without having any idea whether people are receiving it? No! Stay tuned, and I will show you how to query the metrics API to determine how your sending has gone.

Till then, sign up for SparkPost, learn how to manage templates via API, and check out our great blogs on templates! If you have any questions come to the #csharp channel in community slack.

— Mike



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:

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

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.

— Mike

C# library community feature

The community of developers working with SparkPost really has stepped up in the last few months: submitting pull requests, writing new client libraries, finding bugs, and helping each other out in our community Slack. They say you are the company you keep—well, if even a small bit of your collective awesomeness rubs off on us, we’ll know we’ve made it. 🙂

We’d like to show a little bit of love in return by highlighting some of the community members who’ve helped raise the bar for SparkPost and our tools. Today, I’ll start with Darren Cauthon, who contributed the SparkPost C# client library. I asked Darren to share a little bit of his point of view.

How long have you been a developer and what got you started in the tech world?

I’ve been a developer for over 15 years. I got started with tech in my sophomore year, right around the time my college forces students to pick a major. I thought about being a music teacher or going for a general “business” degree, but I remembered that programming in QA Basic in junior high was fun. So I signed up for my first C++ class and never looked back.

What do you like most about being a developer?

Working with all types of people to solve new problems. The tech is fun, but using it to solve actual problems that exist in reality makes it very fulfilling.

What led you to contribute to open source projects?

Two things. First, I got over the fear that my code wasn’t good enough. Second, I’ve found it’s hard to grow as a developer when I’m limited to solving the problems that my business has. Open source provides the opportunity to solve problems that I’d otherwise never think to solve, and it provides a chance to work with developers I’d otherwise never know.

How did you find SparkPost?

My company was about to deploy a new Mandrill solution when their big shakeup occurred. We looked for alternatives, and my boss noticed SparkPost due to your relationship with Port25 (which we used for other solutions).

What prompted you to create the C# client library for us?

I saw there wasn’t one, and I wanted the experience of writing the library. I’ve learned a lot about email processing and C# features while working on the library, and that’s knowledge I’d never have gained otherwise. I’ll be able to apply that knowledge to many more things than just this library.

What’s the hardest thing about contributing to an open source project?

Saying “no” to contributors. Sometimes someone may offer a pull request with a feature or change that doesn’t fit. I hate having to say “no” and reject what another developer has spent time writing. But luckily I haven’t had that problem with this library, as we’ve had a great group of developers contribute new features—and every contribution has fit.

What are you passionate about outside of work?

I have a great family, and raising kids is fun. I’ve been a tuba player for over twenty years, and I’m slowly working towards a black-belt in Tae Kwon Do. I have a 2016 resolution to beat Ninja Gaiden without dying, so I like older console gaming. But my first passion is still programming.

I was really glad to have a chance to talk with Darren and learn more about his point of view. His project really has been a great addition to the ways folks can use SparkPost. Thanks, Darren!

Do you have an idea or project to contribute to this great community of developers? Give us a shout on the SparkPost community Slack, and you might wind up in our new community features series.


p.s. you can check out another one of Darren’s C# libraries here.