Agent feedback

Agent feedback lets an agent or a developer tell us a paperplane response was wrong, a docs page or tool description misled them, or a missing feature blocks the task. It is one request, it works over REST and MCP, and the reports go to the paperplane team. Nothing is published.

When to report

Report a response that is wrong, incomplete or different from the documentation, an error you did not expect, or a missing feature that blocks the task. Send one report per problem. Do not report errors you can fix by changing the request. A validation_error that names a field is the API doing its job; fix the field. Do not use feedback to ask for help with a letter. Reports are read by people, not in real time, and a letter that is stuck is a different job: poll get_letter_status and see Cancel & track.

What to send

POST https://sendpaperplane.com/v1/feedback with these fields:

Field	Required	Description
`category`	Yes	`bug`, `docs_mismatch`, `friction`, `feature_gap`, `quality_degradation`, or `other`.
`note`	Yes	What went wrong and what you expected, up to 4,000 characters.
`order_id`	One of `order_id`, `url`, `surface`	The order the report is about, such as `ord_1a2b3c4d5e6f7a8b`.
`url`	One of `order_id`, `url`, `surface`	The page the report is about, such as a docs page. Query strings and fragments are dropped.
`surface`	One of `order_id`, `url`, `surface`	The endpoint or tool the report is about, such as `POST /v1/orders` or `send_letter`.

curl -X POST https://sendpaperplane.com/v1/feedback \
  -H 'Content-Type: application/json' \
  -d '{
    "category": "docs_mismatch",
    "note": "The quote response lists a tracking line for first_class when tracking is false. The docs say tracking is only itemised when requested.",
    "surface": "POST /v1/quotes"
  }'

import requests

requests.post(
    "https://sendpaperplane.com/v1/feedback",
    json={
        "category": "bug",
        "note": "get_letter_status returned mailed for an order the docs say is still screening.",
        "order_id": "ord_1a2b3c4d5e6f7a8b",
    },
)

With an order_id we can look at the exact order. We record it without checking it, so a mistyped id never makes a report fail, and nothing in the response tells you whether an order exists.

From MCP

The same report is the submit_feedback tool on the MCP server. It takes the same fields and returns the same feedback_id.

submit_feedback(
  category="docs_mismatch",
  note="send_letter's description says the token lasts 30 minutes; mine expired at 15.",
  surface="send_letter"
)

It is not a read and not a spend: it records one private report, mails nothing and charges nothing. It needs no scope, so a key minted with mail:quote only, a key with no scopes at all, and an anonymous caller can all report.

Response and limits

{ "status": "ok", "feedback_id": "fbk_a1b2c3d4e5f6", "already_submitted": false }

Reporting the same thing again from the same caller returns the original feedback_id with already_submitted: true instead of creating a duplicate. A new report returns 201; a repeat returns 200. Feedback has its own rate limit of 10 reports a minute per caller (API key, else IP), separate from every other route, so an integration that is being throttled elsewhere can still report it. A throttled report is 429 rate_limited with a Retry-After header.

What we do with the note

The note is written by whoever called the API, and an agent may be relaying text it read on a page it did not write. We treat it that way: it is stored as plain text, never rendered as HTML and never handed to a model as instructions. Keep API keys, tokens and personal data out of the note. Strings shaped like paperplane API keys, capability and confirmation tokens, credit codes, bearer headers and payment payloads are replaced with [redacted] before storage, but nothing can redact a person’s name or address. Describe what happened without pasting a recipient or letter text.

Tell your agent

Add a line like this to your agent’s instructions file, such as AGENTS.md or CLAUDE.md:

If a paperplane response is wrong or differs from the docs, report it once with POST https://sendpaperplane.com/v1/feedback (or the submit_feedback MCP tool). Include the affected order_id when there is one and never include secrets or recipient details.

Get started

Guides

Tutorials

When to report

What to send

From MCP

Response and limits

What we do with the note

Tell your agent

​When to report

​What to send

​From MCP

​Response and limits

​What we do with the note

​Tell your agent

When to report

What to send

From MCP

Response and limits

What we do with the note

Tell your agent