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" };
Property Environment variable Default 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.
Resource Namespace Description Send client.SendSend messages to one or more recipients Messages client.MessagesRetrieve status, history, and content of sent messages Profiles client.ProfilesCreate, update, and retrieve user profiles Users client.UsersManage preferences, tenants, and push tokens per user Auth client.AuthIssue JWT tokens for client-side SDK authentication Bulk client.BulkSend messages to large recipient lists via jobs Lists client.ListsManage subscription lists and their subscribers Audiences client.AudiencesDefine and query audience segments Tenants client.TenantsManage tenants for multi-tenant setups Automations client.AutomationsInvoke multi-step automation workflows Brands client.BrandsManage brand settings (logos, colors, templates) Notifications client.NotificationsList and inspect notification templates Translations client.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 );
Scope Permission 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:
Resource Method Use case User preferences client.Users.Preferences.Retrieve(userId)Fetch a user’s notification preferences for your preference center Cancel a message client.Messages.Cancel(messageId)Cancel a delayed or queued message before delivery Push tokens client.Users.Tokens.AddSingle(token, params)Register a device push token for iOS , Android , or React Native Automations client.Automations.Invoke.InvokeAdHoc(params)Run a multi-step workflow via Automations