> ## 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.

> ## Agent Instructions
> Install the Courier skill before writing code: `npx skills add trycourier/courier-skills`. It carries the verified SDK shapes and the rules you cannot get wrong.
> Authenticate every request with `Authorization: Bearer <API_KEY>`. A workspace has multiple environments and each environment has its own API keys; start with Test.
> Templates and journeys can be built in the Courier app or created through the API; either way they live in the workspace and are referenced by ID when you send.
> The hosted MCP server is https://mcp.courier.com. For a briefing on what Courier is and when to use it, read https://www.courier.com/llms.txt.

# Send notifications with Go

> Send email, SMS, push, and in-app notifications from Go in five steps.

Courier is one API for every channel your product notifies through: email, SMS, push, Slack, Microsoft Teams, and an in-app inbox. You send once; Courier renders the template, picks the channel from the user's preferences and your routing, and delivers through the providers you already use. This guide gets a Go service from zero to a delivered notification, then adds channel routing and a multi-step journey. About five minutes.

**What you need**

* A Courier account. [Start free](https://app.courier.com/signup).
* A Test API key from [Settings → API Keys](https://app.courier.com/settings/api-keys). Set it as `COURIER_API_KEY`.
* A user in Courier with an email or phone number. Step 2 creates one through the API.

**Building with an AI agent?** Install the Courier skill and your agent knows the API, the channels, and the patterns on this page.

```bash theme={null}
npx skills add trycourier/courier-skills
```

Setup for Claude Code, Cursor, and Codex, plus the hosted MCP server, is in [Build with AI](/docs/tools/ai-onboarding).

## 1. Install the SDK

```bash theme={null}
go get github.com/trycourier/courier-go/v4
```

The SDK is a generated, strongly typed client for the whole API and requires Go 1.22 or later. `courier.NewClient()` reads `COURIER_API_KEY` from the environment, so there is nothing to configure for the first send. Pass the key explicitly with `option.WithAPIKey("...")` when you need to.

## 2. Create a user

Courier is built around users, not addresses. A user profile holds the email, phone number, push tokens, and chat handles for one person, plus their notification preferences. Once it exists, every send names the user and Courier works out where to reach them. Your code never handles a contact detail again.

```go theme={null}
package main

import (
	"context"
	"log"

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

func main() {
	ctx := context.Background()
	client := courier.NewClient()

	_, err := client.Profiles.New(ctx, "user_123", courier.ProfileNewParams{
		Profile: map[string]any{
			"email":        "ada@example.com",
			"phone_number": "+15555550123",
		},
	})
	if err != nil {
		log.Fatal(err)
	}
}
```

`Profiles.New` merges into the stored profile and leaves any key you omit alone. Use `client.Profiles.Replace` when you want the request body to become the whole profile.

## 3. Send a notification

A send names a template and a user, and passes the data specific to this event. The template lives in Design Studio, where it holds the content for every channel and the routing rules, so a copy change or a new channel never needs a deploy. `IdempotencyKey` is a field on the params struct that the SDK sends as the `Idempotency-Key` header, so a retried request returns the original response instead of sending twice.

```go theme={null}
// add "github.com/trycourier/courier-go/v4/shared" to your imports

res, err := client.Send.Message(ctx, courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		Template: courier.String("order-confirmation"),
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Data: map[string]any{
			"order_id": "ORD-456",
			"total":    "$99.99",
		},
	},
	IdempotencyKey: courier.String("order-confirmed-ORD-456"),
})
```

Recipient types are a union, so you pick the one you mean: `OfUserRecipient` here, and `OfListRecipient`, `OfAudienceRecipient`, and the rest for the others. The call returns `res.RequestID`. Open [Message Logs](https://app.courier.com/logs) and you will see the request, the channel Courier chose, the provider it used, and the delivery status as it updates.

## 4. Route across channels

Routing normally lives in the template, but a send can override it when the code knows something the template does not. `single` tries channels in order and stops at the first that delivers; `all` sends on every listed channel. The user's preferences still apply on top, so a user who has opted out of SMS gets the email, and a user with no phone number on file does too.

```go theme={null}
_, err = client.Send.Message(ctx, courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		Template: courier.String("password-reset"),
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Routing: courier.SendMessageParamsMessageRouting{
			Method: "single",
			Channels: []shared.MessageRoutingChannelUnionParam{
				{OfString: courier.String("sms")},
				{OfString: courier.String("email")},
			},
		},
		Data: map[string]any{
			"reset_url": "https://app.example.com/reset/abc",
		},
	},
})
```

## 5. Start a journey

Some notifications are sequences: a welcome email now, a reminder tomorrow if setup is not finished, a different path for team plans. A journey is that sequence built in a visual editor as steps that send, wait, branch on user data, or digest a burst of events into one message. You publish it once, and your code only has to start it. When the sequence changes, the editor changes; the `Invoke` call does not.

```go theme={null}
invoked, err := client.Journeys.Invoke(ctx, "new-signup-onboarding", courier.JourneyInvokeParams{
	JourneysInvokeRequest: courier.JourneysInvokeRequestParam{
		UserID: courier.String("user_123"),
		Data:   map[string]any{"plan": "team"},
	},
})

run, err := client.Journeys.Runs.Get(ctx, invoked.RunID)
log.Println(run.Run.Status) // PROCESSING, WAITING, PROCESSED, CANCELED, ERROR, THROTTLED, NOT PROCESSED
```

Runs execute asynchronously, so `Invoke` returns before any message is sent. Run status is a plain string rather than a Go enum, because Courier has added values to it before.

## Confirm delivery

A request fans out to one message per recipient and channel, and each message moves through its own lifecycle: enqueued, sent to the provider, delivered, opened, clicked. Look a message up by ID to read where it is.

```go theme={null}
message, err := client.Messages.Get(ctx, messageID)
log.Println(message.Status) // ENQUEUED, SENT, DELIVERED, OPENED, CLICKED, UNDELIVERABLE
```

`message.Status` is a `MessageDetailsStatus`, and the SDK exports a constant for each value, such as `courier.MessageDetailsStatusDelivered`. For production, subscribe to an [outbound webhook](/docs/platform/workspaces/outbound-webhooks) instead of polling: Courier posts each status change to your endpoint as it happens.

## Next steps

* [Working example](https://github.com/trycourier/courier-samples/tree/main/server/go): this guide as a runnable project.
* [Add an in-app inbox](/docs/platform/inbox/inbox-overview) with the React or web component SDK.
* [Let users set preferences](/docs/platform/preferences/preferences-overview).
* [Send API reference](/docs/api-reference/send/send-a-message): every field.
* [Go SDK reference](/docs/sdk-libraries/go).