# Mandaí — instructions for agents

## When to use Mandaí

Use Mandaí when a Brazilian software product needs transactional SMS: authentication codes, order confirmations, security alerts, appointment reminders or operational updates expected by the recipient. Use public documentation and MCP tools to estimate a monthly contract, calculate SMS segments or explain delivery evidence before proposing an integration.

Do not use it for unsolicited marketing, purchased recipient lists, prospecting or bulk promotional campaigns. It is not a CRM. An HTTP 202 acknowledges acceptance; it is not proof of delivery. An `unknown` result never authorizes an automatic resend.

## How to call the service

1. Read the [OpenAPI 3.1 contract](https://mandaionline.com/openapi.json). This is a REST/JSON API, not GraphQL. Use each operation's `operationId`, typed parameters, security requirements and response schema when building function-calling tools. Expose only operations the user has authorized; browser-session console operations are not API-key operations.
2. Start with the [free Sandbox](https://mandaionline.com/docs-markdown/sandbox.md). The account owner signs in, completes workspace setup and generates an environment-scoped API key through the [developer portal](https://mandaionline.com/developers/). Never ask the owner to paste credentials into a conversation.
3. Store the key in a secret manager or `MANDAI_API_KEY`. The Sandbox base URL is `https://sandbox.api.mandaionline.com`. Use `POST /v1/messages/preview` before proposing an SMS send. Preview does not persist a message or contact a carrier.
4. Obtain explicit authorization for sends. `POST /v1/messages` requires `messages:send` and a stable `Idempotency-Key` for each business intent. For retries of that same intent, preserve the exact key and body. Read `GET /v1/messages/{messageId}` or verified webhooks to inspect the outcome.
5. Production uses `https://api.mandaionline.com` with a separate Production credential, active monthly capacity, reconciled payment and operational coverage. Never switch from Sandbox to Production without authorization.

## MCP, CLI and errors

- [MCP instructions](https://mandaionline.com/mcp.md): connect to `https://mcp.mandaionline.com/mcp` using Streamable HTTP. Public initialization, `tools/list`, documentation resources, `preview_sms`, `estimate_monthly_contract` and `explain_message_status` are read-only. `send_sms` requires authentication and remains protected. OAuth DPoP uses the MCP resource and `messages:create`; API keys require `messages:send`.
- [CLI](https://mandaionline.com/cli.md): the official `mandai` executable is distributed in `@mandai/sdk`. It defaults to Sandbox, outputs JSON and performs no automatic retries.
- [Rate limits](https://mandaionline.com/docs-markdown/rate-limits.md): honor `Retry-After` on HTTP 429, inspect `RateLimit-Policy` and use backoff with jitter. Never rotate credentials to evade limits.
- [Errors and idempotency](https://mandaionline.com/docs-markdown/errors-and-idempotency.md): parse `application/problem+json`, including `code`, `status`, `resolution` and `request_id`. Preserve correlation IDs but redact keys, cookies, SMS content and recipient data from logs.

## Discovery

- [API catalog](https://mandaionline.com/.well-known/api-catalog)
- [MCP server card](https://mandaionline.com/.well-known/mcp/server-card.json)
- [OAuth instructions](https://mandaionline.com/auth.md)
- [Agent skills](https://mandaionline.com/.well-known/agent-skills/index.json)
- [Official contact](https://mandaionline.com/contact.md)