Skip to main content
The Courier Java SDK gives typed access to the Courier REST API from Java 8+. It uses builder-pattern request construction, OkHttp for transport, and returns strongly typed response objects. Available on GitHub and Maven Central.

Installation

Replace LATEST_VERSION with the current version from Maven Central. Requires Java 8+.

Quick start

CourierOkHttpClient.fromEnv() reads COURIER_API_KEY from your environment, or the courier.apiKey system property. The builder also takes it: .apiKey("YOUR_COURIER_API_KEY").

Authentication

Get your API key from Platform → API Keys in the Courier dashboard. Set it as an environment variable:
Or pass it via the builder:

Sending notifications

Design your notification in Design Studio, then reference it by ID:

Available resources

The SDK covers the full Courier API. Every method returns strongly typed response objects.

Common operations

Checking message status

Managing user profiles

Issuing JWT tokens

Courier’s client-side SDKs (React, JavaScript, mobile) authenticate users with a JWT your backend issues. Authenticate users covers the token flow, the scope strings, and token refresh. Use client.auth().issueToken:

Configuration

Error handling

When the API returns a non-success status code, the SDK throws a CourierServiceException:

Retries

The SDK retries failed requests up to 2 times with exponential backoff. Configure globally:

Timeouts

Requests time out after 60 seconds by default. Configure globally:
Or override per-request using withOptions:

Journeys

Journeys are multi-step workflows: send, delay, branch, throttle, digest, and more. Invoke one by ID or alias to start a run. Cancel runs by ID, or by a shared cancelation token.
Cancel a run with client.journeys().cancel(...), passing exactly one of run_id or cancelation_token (spelled with one “l”). Build and manage journeys from code with create, list, publish, and archive. See Build journeys via API.

More operations

A few more resources from the full Courier REST API:

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.

Idempotent sends

Pass an idempotency key and Courier replays the first response for that key instead of sending again. The SDK sets the Idempotency-Key header for you. Idempotency covers the scoping rule and the replay window.