> ## 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 several environments and each has its own keys, which are plain `pk_` strings with no environment prefix. Start with Test.
> Send with `client.send.message` from the Node SDK (`@trycourier/courier` v7 and later, where the client is the default import). Reference a template by its `nt_` id or its alias.
> A send accepts a bare Elemental element list, but storing content on a template requires the top-level elements wrapped in a channel element.
> To translate a template, write one locale at a time with `PUT /notifications/{id}/locales/{localeId}`, which merges into the existing translations. `PUT /notifications/{id}/content` and `PUT /notifications/{id}/elements/{elementId}` overwrite translations along with the content, so send each element's `id` and `locales` back, and first remove every `checksum` and any `locales` key that starts with an underscore.
> 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.
> Prefer the Guides tab for how-do-I questions and the Docs tab for how-does-it-behave questions. The API reference lives under /api-reference.

# Feedback API: report Courier bugs and feature requests

> Your agent reports Courier bugs and feature requests as it works, and you can file your own through MCP or the API.

Your agent often notices things about Courier before you do, like an error it can't explain or a feature that would make life easier. With the Feedback API, it reports them to Courier's team on its own and keeps working.

You can also file a report yourself, through the [MCP server](https://www.courier.com/docs/resources/mcp.md), the [CLI](https://www.courier.com/docs/resources/cli.md), an SDK, or [`POST /feedback`](https://www.courier.com/docs/api-reference/feedback/submit-feedback):

```javascript Node.js theme={null}
import Courier from "@trycourier/courier";

const client = new Courier({ apiKey: process.env.COURIER_API_KEY });

const report = await client.feedback.create({
  category: "confusing_behavior",
  surface: "api",
  title: "Template variable renders empty in a sent email",
  description:
    "Sending order confirmations with POST /send and template nt_01kx4h2jdafq8bk9aftxak4b40, with order_id in data. The template uses {{order_id}}, and the email showed the heading without the order number.",
  location: "POST /send",
  expected_behavior: "The email shows the order number.",
  request_id: "1-67f340b1-58b7b231d9485ef0cda0a38b",
});

console.log(report.feedback_id);
```

```python Python theme={null}
from courier import Courier

client = Courier()  # reads COURIER_API_KEY

report = client.feedback.create(
    category="confusing_behavior",
    surface="api",
    title="Template variable renders empty in a sent email",
    description="Sending order confirmations with POST /send and template nt_01kx4h2jdafq8bk9aftxak4b40, with order_id in data. The template uses {{order_id}}, and the email showed the heading without the order number.",
    location="POST /send",
    expected_behavior="The email shows the order number.",
    request_id="1-67f340b1-58b7b231d9485ef0cda0a38b",
)

print(report.feedback_id)
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/feedback \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "confusing_behavior",
    "surface": "api",
    "title": "Template variable renders empty in a sent email",
    "description": "Sending order confirmations with POST /send and template nt_01kx4h2jdafq8bk9aftxak4b40, with order_id in data. The template uses {{order_id}}, and the email showed the heading without the order number.",
    "location": "POST /send",
    "expected_behavior": "The email shows the order number.",
    "request_id": "1-67f340b1-58b7b231d9485ef0cda0a38b"
  }'
```

```ruby Ruby theme={null}
require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

report = courier.feedback.create(
  category: :confusing_behavior,
  surface: :api,
  title: "Template variable renders empty in a sent email",
  description: "Sending order confirmations with POST /send and template nt_01kx4h2jdafq8bk9aftxak4b40, with order_id in data. The template uses {{order_id}}, and the email showed the heading without the order number.",
  location: "POST /send",
  expected_behavior: "The email shows the order number.",
  request_id: "1-67f340b1-58b7b231d9485ef0cda0a38b"
)

puts(report.feedback_id)
```

```go Go theme={null}
import (
	"context"
	"fmt"
	"os"

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

client := courier.NewClient(option.WithAPIKey(os.Getenv("COURIER_API_KEY")))

report, err := client.Feedback.New(context.TODO(), courier.FeedbackNewParams{
	Category:         courier.FeedbackNewParamsCategoryConfusingBehavior,
	Surface:          courier.FeedbackNewParamsSurfaceAPI,
	Title:            "Template variable renders empty in a sent email",
	Description:      "Sending order confirmations with POST /send and template nt_01kx4h2jdafq8bk9aftxak4b40, with order_id in data. The template uses {{order_id}}, and the email showed the heading without the order number.",
	Location:         courier.String("POST /send"),
	ExpectedBehavior: courier.String("The email shows the order number."),
	RequestID:        courier.String("1-67f340b1-58b7b231d9485ef0cda0a38b"),
})
if err != nil {
	panic(err.Error())
}

fmt.Println(report.FeedbackID)
```

```java Java theme={null}
import com.courier.client.CourierClient;
import com.courier.client.okhttp.CourierOkHttpClient;
import com.courier.models.feedback.FeedbackCreateParams;
import com.courier.models.feedback.FeedbackCreateResponse;

CourierClient client = CourierOkHttpClient.fromEnv(); // reads COURIER_API_KEY

FeedbackCreateResponse report = client.feedback().create(
    FeedbackCreateParams.builder()
        .category(FeedbackCreateParams.Category.CONFUSING_BEHAVIOR)
        .surface(FeedbackCreateParams.Surface.API)
        .title("Template variable renders empty in a sent email")
        .description("Sending order confirmations with POST /send and template nt_01kx4h2jdafq8bk9aftxak4b40, with order_id in data. The template uses {{order_id}}, and the email showed the heading without the order number.")
        .location("POST /send")
        .expectedBehavior("The email shows the order number.")
        .requestId("1-67f340b1-58b7b231d9485ef0cda0a38b")
        .build());

System.out.println(report.feedbackId());
```

```php PHP theme={null}
use Courier\Client;

$client = new Client(apiKey: getenv('COURIER_API_KEY'));

$report = $client->feedback->create(
  category: 'confusing_behavior',
  surface: 'api',
  title: 'Template variable renders empty in a sent email',
  description: 'Sending order confirmations with POST /send and template nt_01kx4h2jdafq8bk9aftxak4b40, with order_id in data. The template uses {{order_id}}, and the email showed the heading without the order number.',
  location: 'POST /send',
  expectedBehavior: 'The email shows the order number.',
  requestID: '1-67f340b1-58b7b231d9485ef0cda0a38b',
);

echo $report->feedbackID;
```

```csharp C# theme={null}
using TryCourier;
using TryCourier.Models.Feedback;

CourierClient client = new() { ApiKey = Environment.GetEnvironmentVariable("COURIER_API_KEY") };

var report = await client.Feedback.Create(new()
{
    Category = Category.ConfusingBehavior,
    Surface = Surface.Api,
    Title = "Template variable renders empty in a sent email",
    Description = "Sending order confirmations with POST /send and template nt_01kx4h2jdafq8bk9aftxak4b40, with order_id in data. The template uses {{order_id}}, and the email showed the heading without the order number.",
    Location = "POST /send",
    ExpectedBehavior = "The email shows the order number.",
    RequestID = "1-67f340b1-58b7b231d9485ef0cda0a38b",
});

Console.WriteLine(report.FeedbackID);
```

```bash CLI theme={null}
courier feedback create \
  --category confusing_behavior \
  --surface api \
  --title "Template variable renders empty in a sent email" \
  --description "Sending order confirmations with POST /send and template nt_01kx4h2jdafq8bk9aftxak4b40, with order_id in data. The template uses {{order_id}}, and the email showed the heading without the order number." \
  --location "POST /send" \
  --expected-behavior "The email shows the order number." \
  --request-id "1-67f340b1-58b7b231d9485ef0cda0a38b"
```

```text MCP theme={null}
With Courier MCP, report confusing behavior: I sent template nt_01kx4h2jdafq8bk9aftxak4b40 with POST /send and order_id in data. The template uses {{order_id}}, and the email showed the heading without the order number. I expected the order number to appear. The request ID is 1-67f340b1-58b7b231d9485ef0cda0a38b.
```

A `201` returns the report's ID, `fbk_` followed by a ULID. Courier's team and their agents read every piece of feedback in real time.

## What goes in a report

Four fields are required. The optional ones give Courier's team what it needs to act on a report quickly.

| Field | Required | What to include |
| - | - | - |
| `category` | Yes | The type of feedback: a bug, confusing behavior, a feature request, or something else. See [Categories](#categories) |
| `surface` | Yes | Where it happened: `api`, `sdk`, `mcp`, `ui` (the Courier app), `docs`, or `other` |
| `title` | Yes | A one-line summary of the issue or idea |
| `description` | Yes | A detailed account of what's going on, or what you'd like Courier to do |
| `location` | No | Where it happened: an endpoint such as [`POST /send`](https://www.courier.com/docs/api-reference/send/send-a-message), an SDK method, an MCP tool, or the URL of a page in the Courier app, docs, or website |
| `expected_behavior` | No | What should happen instead |
| `request_id` | No | The request ID of the API call that shows the problem |
| `model` | No | The AI model sending the report |
| `harness` | No | The agent or tool sending the report, such as Claude Code, Cursor, Codex, or your own script |

### Categories

| Category | Use it when |
| - | - |
| `possible_bug` | Something looks wrong |
| `confusing_behavior` | It works, but it was hard to understand |
| `feature_request` | Courier doesn't do something you need yet |
| `other` | Nothing else fits |

Each field's length limit is in the [API reference](https://www.courier.com/docs/api-reference/feedback/submit-feedback.md).

### Example of a good report

A good report states the goal, the steps, the result, and what you expected, with IDs Courier's team can look up. If you found a fix or workaround, include it:

```json wrap theme={null}
{
  "category": "confusing_behavior",
  "surface": "api",
  "title": "Template metrics return an empty series for an unknown template ID",
  "description": "Goal: chart last week's delivery rate for the order confirmation template. Steps: called GET /notifications/{id}/metrics with lookback P7D and granularity DAY. Result: a 200 with an empty series, so the dashboard showed a template that had stopped sending. The template ID had a typo. With the correct ID, the same call returned real counts.",
  "location": "GET /notifications/{id}/metrics",
  "expected_behavior": "A 404 for a template ID that doesn't exist, so a typo can't look like a template with no sends.",
  "request_id": "1-67f340b1-58b7b231d9485ef0cda0a38b",
  "model": "claude-opus-5-5",
  "harness": "Claude Code"
}
```

**Leave secrets and customer data out of reports.** Describe the problem with IDs, such as a message ID or template ID, instead of API keys, recipient emails, or message content.

## Keys and limits

Send reports with an API key that has no scope restrictions. Each workspace can send 200 reports per day.
