EmmaSharper 8.0.1

EmmaSharper

A .NET client for the Emma (Marigold) API.

This is the maintained continuation of kylegregory/EmmaSharp, which last shipped in 2019, by way of BinaryPatrick/EmmaSharper. Several bugs still shown as open on those repositories are fixed here — see Upstream issues fixed in this fork.

📖 Documentation wiki — getting started, enterprise multi-account use, paging, rate limiting, recipes, and notes on the Emma API's own quirks.

🧪 Runnable samples — dotnet run --project samples/EmmaSharper.Samples -- --help. Built by CI, so the documented patterns are guaranteed to compile.

Targets: netstandard2.0, net8.0, net10.0 — so .NET Framework 4.6.2+ works too. Dependencies: two on the modern targets, both Microsoft.Extensions.*.

Install

dotnet add package EmmaSharper

Quick start

using EmmaSharper;

services.AddEmmaApiProviders(options =>
{
    options.AccountId = "your account id";
    options.PublicKey = "your public key";
    options.SecretKey = "your secret key";
    // options.BaseUrl defaults to https://api.e2ma.net
});

Or bind from configuration — this reads the "Emma" section:

services.AddEmmaApiProviders(builder.Configuration);

{
  "Emma": {
    "AccountId": "your account id",
    "PublicKey": "your public key",
    "SecretKey": "your secret key"
  }
}

Pass sectionName: null to bind the configuration root instead, which is how 7.x behaved.

Then inject any provider:

public sealed class MemberSync(IEmmaMemberProvider members)
{
    public async Task<int> CountActiveAsync(CancellationToken ct)
        => await members.GetMemberCount(cancellationToken: ct);
}

Working with multiple accounts

Emma enterprise accounts authenticate once and then address many subaccounts. Use IEmmaAccountScopeFactory rather than registering a container per account — a scope reuses the same credentials and the same pooled HttpClient, changing only the account segment of the request path.

public sealed class QuotaSweep(IEmmaAccountScopeFactory scopeFactory)
{
    public async Task RunAsync(IEnumerable<string> subaccountIds, CancellationToken ct)
    {
        foreach (string accountId in subaccountIds)
        {
            IEmmaAccountScope scope = scopeFactory.ForAccount(accountId);
            int active = await scope.Members.GetMemberCount(cancellationToken: ct);
        }
    }
}

Rate limiting

Emma signals throttling with 403 Forbidden as well as the conventional 429. This is the least obvious behaviour in the API — a naive client reads the 403 as an auth failure and gives up instead of backing off.

Both map to EmmaRateLimitException, which carries RetryAfter when Emma supplies it:

try
{
    await members.GetMemberCount(cancellationToken: ct);
}
catch (EmmaRateLimitException ex)
{
    await Task.Delay(ex.RetryAfter ?? TimeSpan.FromSeconds(5), ct);
}

AddEmmaApiProviders returns the IHttpClientBuilder, so you can attach a resilience handler instead of catching:

services.AddEmmaApiProviders(configuration)
        .AddStandardResilienceHandler();

If you do, raise the per-attempt timeout. The standard handler defaults to 10 seconds, which is not enough to fetch a 500-record member page.

Errors

Every non-success response raises EmmaException with typed detail — no string matching required:

catch (EmmaException ex)
{
    logger.LogError("Emma {Status} on {Method} {Resource}: {Body}",
        ex.StatusCode, ex.Method, ex.Resource, ex.ResponseBody);
}

Providers

All methods are asynchronous and accept a trailing CancellationToken.

Paging

Endpoints that page take start and end. Emma's range is inclusive, so a 500-record page is end = start + 499. Omit both and you get the first page.

Versioning

8.0.0 is a breaking release — see the changelog. The short version: RestSharp and Newtonsoft.Json removed, EmmaException no longer exposes a RestSharp type, ids widened from int to long, and every method gained a CancellationToken.

Contributing

This project is not affiliated with Emma. Everyone working on it is a volunteer. Fork the repo, make your changes, and open a pull request — CI builds all three target frameworks, runs the tests on net472, net8.0 and net10.0, and runs CodeQL.

Emma's own API documentation is at https://api.myemma.com/.