Courier Go SDK

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.SendMessageParamsMessageContentUnion{
			OfElementalContentSugar: &shared.ElementalContentSugarParam{
				Title: "Order shipped",
				Body:  "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.

Resource	Namespace	Description
Send	`client.Send`	Send messages to one or more recipients
Messages	`client.Messages`	Retrieve status, history, and content of sent messages
Profiles	`client.Profiles`	Create, update, and retrieve user profiles
Users	`client.Users`	Manage preferences, tenants, and push tokens per user
Auth	`client.Auth`	Issue JWT tokens for client-side SDK authentication
Bulk	`client.Bulk`	Send messages to large recipient lists via jobs
Lists	`client.Lists`	Manage subscription lists and their subscribers
Audiences	`client.Audiences`	Define and query audience segments
Tenants	`client.Tenants`	Manage tenants for multi-tenant setups
Journeys	`client.Journeys`	Invoke and cancel runs; create, list, publish, and archive journeys
Brands	`client.Brands`	Manage brand settings (logos, colors, templates)
Notifications	`client.Notifications`	List and inspect notification templates
Translations	`client.Translations`	Manage localized content

Common Operations

Checking Message Status

message, err := client.Messages.Get(context.TODO(), "your-message-id")
fmt.Println(message.Status)
fmt.Println(message.Delivered) // Unix ms timestamp; 0 until delivered

Managing User Profiles

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

profile, err := client.Profiles.Get(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)

Scope	Permission
`user_id:<id>`	Which user the token is for (required)
`inbox:read:messages`	Read inbox messages
`inbox:write:events`	Mark messages as read/archived
`read:preferences`	Read notification preferences
`write:preferences`	Update notification preferences
`write:user-tokens`	Register 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.Error())
	}
}

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

The SDK sets no request timeout by default. Add one with a context deadline (or the option.WithRequestTimeout client option):

ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
defer cancel()

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

Journeys

Journeys are multi-step workflows (send, delay, branch, throttle, digest, and more). Invoke one by ID or alias to start a run, then cancel runs by ID or a shared cancelation token.

// Start a run (by journey ID or alias); the response includes a RunID
response, err := client.Journeys.Invoke(context.TODO(), "your-journey-id", courier.JourneyInvokeParams{
    JourneysInvokeRequest: courier.JourneysInvokeRequestParam{
        UserID: courier.String("user_123"),
        Data:   map[string]any{"orderId": "A-1042"},
    },
})

// Cancel one run, or every run sharing a cancelation token
_, err = client.Journeys.Cancel(context.TODO(), courier.JourneyCancelParams{
    CancelJourneyRequest: courier.CancelJourneyRequestParamOfByRunID(response.RunID),
})

cancel takes exactly one of run_id or cancelation_token (spelled with one “l”). You can also build and manage journeys from code (create, list, publish, archive). See Build journeys via API.

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.Get(ctx, userId, courier.UserPreferenceGetParams{})`	Fetch a user’s notification preferences for your preference center
Cancel a message	`client.Messages.Cancel(ctx, messageId)`	Cancel a delayed or queued message before delivery
Push tokens	`client.Users.Tokens.AddSingle(ctx, token, params)`	Register a device push token for iOS, Android, React Native, or Flutter

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.

Client-side SDKs

Server-side SDKs

Installation

Quick Start

Authentication

Sending Notifications

With a template

With inline content

Available Resources

Common Operations

Checking Message Status

Managing User Profiles

Issuing JWT Tokens

Configuration

Error Handling

Retries

Timeouts

Journeys

More Operations

API Reference

Send API

Quickstart

GitHub

​Installation

​Quick Start

​Authentication

​Sending Notifications

​With a template

​With inline content

​Available Resources

​Common Operations

​Checking Message Status

​Managing User Profiles

​Issuing JWT Tokens

​Configuration

​Error Handling

​Retries

​Timeouts

​Journeys

​More Operations

API Reference

Send API

Quickstart

GitHub

Installation

Quick Start

Authentication

Sending Notifications

With a template

With inline content

Available Resources

Common Operations

Checking Message Status

Managing User Profiles

Issuing JWT Tokens

Configuration

Error Handling

Retries

Timeouts

Journeys

More Operations