Skip to main content
The Courier C# SDK provides typed access to the Courier REST API from applications written in C#. It targets .NET Standard 2.0, uses async/await throughout, and returns strongly typed response objects. Available on GitHub.

Installation

dotnet add package Courier
Requires .NET Standard 2.0 or later.

Quick Start

using Courier;
using Courier.Models;
using Courier.Models.Send;

CourierClient client = new();

var response = await client.Send.Message(new SendMessageParams
{
    Message = new()
    {
        To = new UserRecipient { Email = "you@example.com" },
        Content = new()
        {
            Title = "Hello from Courier!",
            Body = "Your first notification, sent with the C# SDK.",
        },
    },
});

Console.WriteLine(response.RequestId);
The client reads COURIER_API_KEY from your environment automatically. You can also set it explicitly: new CourierClient { ApiKey = "your-key" }.

Authentication

Get your API key from Settings > API Keys in the Courier dashboard. Set it as an environment variable:
export COURIER_API_KEY="your-api-key"
Or pass it to the client:
CourierClient client = new() { ApiKey = "your-api-key" };
PropertyEnvironment variableDefault
ApiKeyCOURIER_API_KEY
BaseUrlCOURIER_BASE_URLhttps://api.courier.com

Sending Notifications

With a template

var response = await client.Send.Message(new SendMessageParams
{
    Message = new()
    {
        To = new UserRecipient { UserId = "user_123" },
        Template = "my-template-id",
        Data = new Dictionary<string, JsonElement>
        {
            { "orderNumber", JsonSerializer.SerializeToElement("10042") },
        },
    },
});

With inline content

var response = await client.Send.Message(new SendMessageParams
{
    Message = new()
    {
        To = new UserRecipient { Email = "jane@example.com" },
        Content = new()
        {
            Title = "Order shipped",
            Body = "Your order {{orderNumber}} has shipped!",
        },
        Data = new Dictionary<string, JsonElement>
        {
            { "orderNumber", JsonSerializer.SerializeToElement("10042") },
        },
    },
});

Available Resources

The SDK covers the full Courier API. Every method is async and returns strongly typed models.
ResourceNamespaceDescription
Sendclient.SendSend messages to one or more recipients
Messagesclient.MessagesRetrieve status, history, and content of sent messages
Profilesclient.ProfilesCreate, update, and retrieve user profiles
Usersclient.UsersManage preferences, tenants, and push tokens per user
Authclient.AuthIssue JWT tokens for client-side SDK authentication
Bulkclient.BulkSend messages to large recipient lists via jobs
Listsclient.ListsManage subscription lists and their subscribers
Audiencesclient.AudiencesDefine and query audience segments
Tenantsclient.TenantsManage tenants for multi-tenant setups
Automationsclient.AutomationsInvoke multi-step automation workflows
Brandsclient.BrandsManage brand settings (logos, colors, templates)
Notificationsclient.NotificationsList and inspect notification templates
Translationsclient.TranslationsManage localized content

Common Operations

Checking Message Status

var message = await client.Messages.Retrieve("your-message-id");
Console.WriteLine(message.Status);
Console.WriteLine(message.Delivered);

Managing User Profiles

await client.Profiles.Create("user_123", new ProfileCreateParams
{
    Profile = new Dictionary<string, object>
    {
        { "email", "jane@example.com" },
        { "name", "Jane Doe" },
    },
});

var profile = await client.Profiles.Retrieve("user_123");

Issuing JWT Tokens

var result = await client.Auth.IssueToken(new AuthIssueTokenParams
{
    Scope = "user_id:user_123 inbox:read:messages inbox:write:events",
    ExpiresIn = "2 days",
});

Console.WriteLine(result.Token);
ScopePermission
user_id:<id>Which user the token is for (required)
inbox:read:messagesRead inbox messages
inbox:write:eventsMark messages as read/archived
read:preferencesRead notification preferences
write:preferencesUpdate notification preferences
write:user-tokensRegister push notification tokens

Configuration

Error Handling

When the API returns a non-success status code, the SDK throws a CourierException:
try
{
    await client.Send.Message(parameters);
}
catch (CourierException e)
{
    Console.WriteLine(e.StatusCode);
    Console.WriteLine(e.Message);
}

Retries and Timeouts

The SDK automatically retries failed requests up to 2 times with exponential backoff. Use WithOptions to configure per-request:
var response = await client
    .WithOptions(options => options with
    {
        Timeout = TimeSpan.FromSeconds(20),
        MaxRetries = 0,
    })
    .Send.Message(parameters);
WithOptions returns a new client instance; the original is unchanged.

More Operations

The SDK covers the full Courier REST API. Here are a few more resources beyond what’s documented above:
ResourceMethodUse case
User preferencesclient.Users.Preferences.Retrieve(userId)Fetch a user’s notification preferences for your preference center
Cancel a messageclient.Messages.Cancel(messageId)Cancel a delayed or queued message before delivery
Push tokensclient.Users.Tokens.AddSingle(token, params)Register a device push token for iOS, Android, or React Native
Automationsclient.Automations.Invoke.InvokeAdHoc(params)Run a multi-step workflow via Automations