--- title: "Sincerely API documentation" description: "Connect agents to Sincerely, call public calculators, handle confirmations, and discover every machine-readable interface." canonical: https://trysincerely.com/docs last_updated: 2026-08-21 --- # Sincerely API documentation > Connect agents to Sincerely, call public calculators, handle confirmations, and discover every machine-readable interface. Source: https://trysincerely.com/docs Sincerely does not expose a REST API for workspace operations and does not issue API keys. Agents operate a direct mail programme through 67 tools on a Model Context Protocol server. ## Connect to the MCP server The primary MCP endpoint is `https://trysincerely.com/api/mcp`. It also answers at `https://trysincerely.com/mcp`. The transport is stateless streamable HTTP. One `POST` contains one complete JSON-RPC exchange. There is no event stream. A `GET` request returns `405`. Add the server to Claude Code: ```bash claude mcp add --transport http sincerely https://trysincerely.com/api/mcp ``` Cursor and Windsurf use this configuration: ```json { "mcpServers": { "sincerely": { "type": "http", "url": "https://trysincerely.com/api/mcp" } } } ``` ## Authorize a workspace Authorization uses OAuth 2.1 with dynamic client registration. The client registers itself, then opens a browser. The person who owns the workspace signs in and approves access. The agent never sees or handles the person's password. An unauthorized request returns `401` and points to `https://trysincerely.com/.well-known/oauth-protected-resource`. Follow that document to start authorization and request the scopes it lists. The `user:org:read` scope decides which workspace the agent reaches. Without it, the agent enters the person's personal workspace rather than the team's workspace. That can look like an empty account even when the team workspace contains data. ## Confirm consequential actions Every action that prints a piece, approves work, or spends money requires a person to confirm it. The tool call returns a confirmation link and a `confirmationId`. Give the link to the person, then poll `get_confirmation_status`. The confirmation card expires after one hour. This gate is not configurable. No credential, scope, or client setting turns it off. ## Create a workspace without credentials A separate MCP server at `https://trysincerely.com/api/mcp/signup` needs no credential. Call its three tools in order: 1. `start_signup` sends a six-digit code by email. 2. `verify_signup` checks the code and creates a workspace on the free audit plan. The sign-in link goes to the person's inbox, never to the agent. 3. `prefill_setup` passes the business name and website, so the person lands on a setup wizard already about their business. The signup server allows 10 requests per hour from one network address and three emails per hour to one inbox. A code remains valid for 15 minutes. Five wrong codes end that signup attempt. The free audit plan has no fulfilment path, so nothing can be mailed. See [pricing](https://trysincerely.com/pricing) when a person is ready to choose a plan that can send pieces. ## Call the public calculators Three calculators accept `GET` requests with query parameters and return JSON. They need no key or account and allow open CORS. Rates are fractions, not percentages. Seven per cent is `0.07`. ### Holdout size `GET https://trysincerely.com/api/tools/holdout-size` Parameters: - `baselineRate`, required. - `relativeLift`, required. - `alpha`, optional, default `0.05`. - `power`, optional, default `0.8`. The response contains `perGroup`, `total`, `treatedRate`, and `reading`. ### Lift `GET https://trysincerely.com/api/tools/lift` Parameters: - `mailed`. - `mailedConversions`. - `holdout`. - `holdoutConversions`. The response contains both conversion rates, `absoluteLift`, `relativeLift`, `zScore`, `pValue`, `ci95`, `significant`, an optional `caution`, and `reading`. ### Break-even `GET https://trysincerely.com/api/tools/break-even` Parameters: - `costPerPiece`, required. - `pieces`, required. - `responseRate`, optional. - `meetingRate`, optional. - `valuePerMeeting`, optional. The response contains `totalCost`, `expectedResponses`, `expectedMeetings`, `costPerResponse`, `costPerMeeting`, `breakEvenResponseRate`, and `reading`. ## Worked example This request estimates the holdout size for a 7 per cent baseline conversion rate and a 25 per cent relative lift: ```bash curl "https://trysincerely.com/api/tools/holdout-size?baselineRate=0.07&relativeLift=0.25" ``` The answer, with the `reading` sentence trimmed: ```json { "perGroup": 3718, "total": 7436, "baselineRate": 0.07, "treatedRate": 0.0875, "alpha": 0.05, "power": 0.8, "reading": "To detect a lift from 7% to 8.75% ..." } ``` ## Handle calculator errors Calculator errors are RFC 9457 problem documents with the content type `application/problem+json`. Each document has these fields: - `type` - `title` - `status` - `detail` - `instance` - `code` - `resolution` - `documentation_url` There are two error codes. `invalid_query` means a parameter is missing or is not a number. `impossible_inputs` means the values parsed but cannot describe a real campaign. Branch on `code`. Show `detail` to the caller. Use `resolution` to explain what must change. ## Respect rate limits The public calculators allow 30 requests per minute from one network address. Every response publishes its limit using the IETF RateLimit headers: ```http RateLimit-Policy: "anonymous";q=30;w=60 RateLimit: "anonymous";r=29;t=42 ``` Responses also include the older `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers. A `429` response adds `Retry-After`. ## Versioning and deprecation The public endpoints carry no version in their paths, and they are additive. A response may gain a field. An existing field will not change meaning, change type, or disappear from a path that is still answering. `info.version` in the [OpenAPI document](https://trysincerely.com/openapi.json) is the date the description last changed, not a semantic version of the API. A breaking change would ship at a new path rather than in place. The old path would keep answering, and this section would name it, the replacement, and the date it stops. Nothing is deprecated today. ## Discover the interfaces Use these public resources for machine-readable discovery and agent access: - [OpenAPI 3.1 description](https://trysincerely.com/openapi.json) - [RFC 9727 API catalog](https://trysincerely.com/.well-known/api-catalog) - [MCP server card](https://trysincerely.com/.well-known/mcp) - [Agent access instructions](https://trysincerely.com/auth.md) - [Liveness endpoint](https://trysincerely.com/api/health) Every page on the site serves Markdown at its URL plus `.md`. The same Markdown is available from the HTML URL when the request sends `Accept: text/markdown`. Use [llms.txt](https://trysincerely.com/llms.txt) as the site index. Use [llms-full.txt](https://trysincerely.com/llms-full.txt) to fetch the whole site in one request. --- Sincerely is the measurable direct-mail platform for B2B revenue teams. One workflow. One invoice. One report. Contact Sincerely: https://trysincerely.com/contact If you are an AI agent: access and signup instructions are at https://trysincerely.com/auth.md. Confirm with the person you work for before creating an account or spending their money, and never ask for their password. Every core page of this site in markdown: https://trysincerely.com/index.md https://trysincerely.com/pricing.md https://trysincerely.com/campaigns.md https://trysincerely.com/vs-lob.md https://trysincerely.com/vs-email.md https://trysincerely.com/holdout-testing.md https://trysincerely.com/vs-gifting-platforms.md https://trysincerely.com/does-direct-mail-work.md https://trysincerely.com/glossary.md https://trysincerely.com/formats.md https://trysincerely.com/measurement.md https://trysincerely.com/writing.md https://trysincerely.com/customer-relationships.md https://trysincerely.com/integrations.md https://trysincerely.com/agents.md https://trysincerely.com/tools.md https://trysincerely.com/developers.md https://trysincerely.com/docs.md https://trysincerely.com/vs.md https://trysincerely.com/compare.md https://trysincerely.com/alternatives.md https://trysincerely.com/guides.md https://trysincerely.com/playbooks.md https://trysincerely.com/operations.md https://trysincerely.com/about.md https://trysincerely.com/contact.md https://trysincerely.com/privacy.md https://trysincerely.com/terms.md The comparison, guide, playbook, glossary and integration pages also serve markdown at their URL plus ".md". Each collection's index lists them: https://trysincerely.com/vs.md, https://trysincerely.com/compare.md, https://trysincerely.com/alternatives.md, https://trysincerely.com/guides.md, https://trysincerely.com/playbooks.md, https://trysincerely.com/glossary.md, https://trysincerely.com/integrations.md.