Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.courier.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

The Courier Go SDK provides typed access to the Courier REST API from applications written in Go. It uses strongly typed request structs with omitzero semantics and returns parsed response types. Available on GitHub and pkg.go.dev.

​
Installation

import (
	"github.com/trycourier/courier-go/v4" // imported as courier
)
Or pin a specific version: 
go get -u 'github.com/trycourier/courier-go/v4'
Requires Go 1.22+.

​
Quick Start

package main

import (
	"context"
	"fmt"

	"github.com/trycourier/courier-go/v4"
	"github.com/trycourier/courier-go/v4/option"
	"github.com/trycourier/courier-go/v4/shared"
)

func main() {
	client := courier.NewClient(
		option.WithAPIKey("My API Key"), // defaults to os.LookupEnv("COURIER_API_KEY")
	)
	response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
		Message: courier.SendMessageParamsMessage{
			To: courier.SendMessageParamsMessageToUnion{
				OfUserRecipient: &shared.UserRecipientParam{
					UserID: courier.String("your_user_id"),
				},
			},
			Template: courier.String("your_template_id"),
			Data: map[string]any{
				"foo": "bar",
			},
		},
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.RequestID)
}
The client reads COURIER_API_KEY from your environment automatically. You can also pass it explicitly with option.WithAPIKey("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"
The SDK picks this up by default. To pass it explicitly: 
client := courier.NewClient(
	option.WithAPIKey("your-api-key"),
)

​
Sending Notifications

​
With a template

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("my-template-id"),
		Data: map[string]any{
			"orderNumber": "10042",
		},
	},
})

​
With inline content

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("jane@example.com"),
			},
		},
		Content: &courier.SendMessageParamsMessageContent{
			Title: courier.String("Order shipped"),
			Body:  courier.String("Your order {{orderNumber}} has shipped!"),
		},
		Data: map[string]any{
			"orderNumber": "10042",
		},
	},
})

​
Available Resources

The SDK covers the full Courier API. Every method is typed and documented with Go docstrings.
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

message, err := client.Messages.Retrieve(context.TODO(), "your-message-id")
fmt.Println(message.Status)
fmt.Println(message.Delivered)

​
Managing User Profiles

_, err := client.Profiles.Create(context.TODO(), "user_123", courier.ProfileCreateParams{
	Profile: map[string]any{
		"email": "jane@example.com",
		"name":  "Jane Doe",
	},
})

profile, err := client.Profiles.Retrieve(context.TODO(), "user_123")

​
Issuing JWT Tokens

result, err := client.Auth.IssueToken(context.TODO(), courier.AuthIssueTokenParams{
	Scope:     "user_id:user_123 inbox:read:messages inbox:write:events",
	ExpiresIn: "2 days",
})
fmt.Println(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 returns an error that can be unwrapped to access status and details: 
response, err := client.Send.Message(context.TODO(), params)
if err != nil {
	var apiErr *courier.Error
	if errors.As(err, &apiErr) {
		fmt.Println(apiErr.StatusCode)
		fmt.Println(apiErr.Message)
	}
}

​
Retries

The SDK automatically retries failed requests up to 2 times with exponential backoff. Configure globally or per-request: 
client := courier.NewClient(
	option.WithMaxRetries(0), // disable retries
)

​
Timeouts

Requests time out after 60 seconds by default. Configure with a custom context or client option: 
ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
defer cancel()

response, err := client.Send.Message(ctx, params)

​
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(ctx, userId)Fetch a user’s notification preferences for your preference center
Cancel a messageclient.Messages.Cancel(ctx, messageId)Cancel a delayed or queued message before delivery
Push tokensclient.Users.Tokens.AddSingle(ctx, token, params)Register a device push token for iOS, Android, or React Native
Automationsclient.Automations.Invoke.InvokeAdHoc(ctx, params)Run a multi-step workflow via Automations

API Reference

Full REST API docs with request/response examples.

Send API

Learn about the Send endpoint, routing, and message options.

Quickstart

Send your first notification in under two minutes.

GitHub

Source code, issues, and changelog.