From 62510cf433e03c481f99c725d497b7a053a41f17 Mon Sep 17 00:00:00 2001 From: Eric Lee Date: Wed, 1 Apr 2026 12:50:23 -0400 Subject: [PATCH] docs: add AGENTS.md for AI coding assistants Provides structured context for AI agents (Cursor, Claude Code, Codex) working with the Courier Java SDK: core send pattern with builder API, key rules (routing defaults, profile merge vs replace, idempotency, bulk flow), concept definitions, and links to full docs/MCP/skills. --- AGENTS.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e231714 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,60 @@ +# Courier Java SDK + +Courier is a notifications API for sending messages across email, SMS, push, in-app inbox, Slack, and WhatsApp from a single API call. + +## Setup + +```java +import com.courier.client.CourierClient; +import com.courier.client.okhttp.CourierOkHttpClient; + +CourierClient client = CourierOkHttpClient.fromEnv(); // reads COURIER_API_KEY from env +``` + +## Core pattern + +```java +import com.courier.core.JsonValue; +import com.courier.models.UserRecipient; +import com.courier.models.send.SendMessageParams; +import com.courier.models.send.SendMessageResponse; + +SendMessageParams params = SendMessageParams.builder() + .message(SendMessageParams.Message.builder() + .to(UserRecipient.builder().userId("user_123").build()) + .template("TEMPLATE_ID") + .data(SendMessageParams.Message.Data.builder() + .putAdditionalProperty("order_id", JsonValue.from("456")) + .build()) + .build()) + .build(); + +SendMessageResponse response = client.send().message(params); +System.out.println(response.requestId()); +``` + +## Key rules + +- Use `routing.method: "single"` (fallback chain) unless the user explicitly asks for parallel delivery (`"all"`). +- Use `client.profiles().create()` for partial profile updates (it merges). Use `client.profiles().replace()` only when fully replacing all profile data. +- Test and production use different API keys from the same workspace. Always confirm which environment before sending. +- For transactional sends (OTP, orders, billing), pass an `Idempotency-Key` header via `.putAdditionalHeader("Idempotency-Key", value)` on the params builder to prevent duplicates. +- Bulk sends are a 3-step flow: `client.bulk().createJob()` → `client.bulk().addUsers()` → `client.bulk().runJob()`. +- `requestId` from a single-recipient send doubles as the `message_id`. For multi-recipient sends, each recipient gets a unique `message_id`. +- Java uses the builder pattern for all params; all model classes are immutable. + +## Concepts + +- `template` — notification template ID from the Courier dashboard +- `routing.method` — `"single"` = try channels in order until one succeeds; `"all"` = send on every channel simultaneously +- `tenant_id` — multi-tenant context; affects brand and preference defaults for the message +- `list_id` — send to all subscribers of a named list +- `UserRecipient` — registered user whose profile has channel addresses +- Ad-hoc recipients: pass email or phone directly in the `to` field (no stored profile needed) + +## More context + +- Full docs index: https://www.courier.com/docs/llms.txt +- API reference: https://www.courier.com/docs/reference/get-started +- MCP server: https://mcp.courier.com +- Courier Skills (Cursor / Claude Code): https://github.com/trycourier/courier-skills