Mailgun.Models.SignedEvent 1.0.0-rc1

This is a prerelease version of Mailgun.Models.SignedEvent.
There is a newer version of this package available.
See the version list below for details.
dotnet add package Mailgun.Models.SignedEvent --version 1.0.0-rc1
NuGet\Install-Package Mailgun.Models.SignedEvent -Version 1.0.0-rc1
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Mailgun.Models.SignedEvent" Version="1.0.0-rc1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Mailgun.Models.SignedEvent --version 1.0.0-rc1
#r "nuget: Mailgun.Models.SignedEvent, 1.0.0-rc1"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Mailgun.Models.SignedEvent as a Cake Addin
#addin nuget:?package=Mailgun.Models.SignedEvent&version=1.0.0-rc1&prerelease

// Install Mailgun.Models.SignedEvent as a Cake Tool
#tool nuget:?package=Mailgun.Models.SignedEvent&version=1.0.0-rc1&prerelease

Mailgun.Models.SignedEvent for incoming Mailgun webhooks

nuget shield

Implements data model for incoming Mailgun events to use with your custom Mailgun webhooks.

This library can be used as a data model for the deserialization of this data with any JSON serializer of your choice. It even provides a handy function to verify its cryptographic signature.

Since it targets .NET Standard 1.6 it is compatible with a wide variety of platforms (such as .NET Framework 4.6.1, .NET Core 1.0 and newer).

Background

According to Mailgun they provide developer friendly transactional e-mail service. In spite of this claim there's still no official SDK for nearly any platform and their documentation often lacks basic information. However it's still one of the best options you have if you don't want to implement your own e-mail delivery service which can become very complex very quickly.

Once you have an account with them you can subscribe to various messaging events so when the appropriate event happens (eg. the e-mail was delivered or bounced) Mailgun will POST a JSON encoded object to the URL you provided.

This library was created to ease the burden of deserializing these events into POCOs and to provide an easy way to verify the cryptographic signature of an incoming packet.

Usage

Installation

Add this package as a dependency to your project using NuGet.

Example

Here's a practical example using ASP.NET Core 3.1:

using Mailgun.Models.SignedEvent;

...

[Route("[controller]")]
[ApiController]
public class DeliveredController : ControllerBase
{
    [HttpPost]
    public async Task<ActionResult<SignedEvent>> PostDelivered([FromBody] SignedEvent signedEvent)
    {
        // ASP.NET Core framework will automagically deserialize JSON into signedEvent (see notes at the bottom regarding caveats)
        if (!signedEvent.Signature.IsValid("your-api-key"))
        {
            // if the signature is invalid, return 401
            return Unauthorized();
        }

        // do something meaningful with signedEvent.Event here

        // finally return 201 so Mailgun knows POST has been successful. Otherwise it'll keep retrying
        return CreatedAtAction(nameof(PostDelivered), null);
    }
}

A SignedEvent contains a Signature and the actual Event. While not mandatory it's recommended to check the signature to make sure it was actually signed by Mailgun.

Since the signature is created using the signing server's own time you can specify how old a signature can be to still be considered as valid. By default this is set to 10 minutes.

Important Notes

Unusual JSON Naming Convention

Mailgun generates JSON data using an unusual naming convention with dashes between words. This means that the verb is valid will be encoded as is-valid even though the convention is to encode names as camelCase (resulting in isValid).

There are ways to configure most JSON serializers to handle this, but this topic is out of scope of this project.

Structure Is Constantly Changing

Please note that these events can apparently change their structure anytime, so don't be surprised if the data you've just received contains new fields.

If you discover a change (which can only be an addition according to their documentation) you're welcome to open a PR.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp1.0 was computed.  netcoreapp1.1 was computed.  netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard1.6 is compatible.  netstandard2.0 was computed.  netstandard2.1 was computed. 
.NET Framework net461 is compatible.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen30 was computed.  tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Mailgun.Models.SignedEvent:

Package Downloads
Mailgun.Middleware.AuthenticationHandler

Package Description

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.1.1 4,225 6/29/2020
1.1.0 438 6/22/2020
1.0.2 488 6/22/2020
1.0.1 470 6/19/2020
1.0.0 478 6/18/2020
1.0.0-rc1 331 6/18/2020
1.0.0-rc0 281 6/18/2020