# Edwyna

Edwyna is an API-only service for individual and transactional outbound faxes to supported United States and Canadian numbers. It is not for bulk faxing, marketing, number discovery, or fax-list campaigns.

Human documentation: https://edwyna.com/api
OpenAPI 3.1 contract: https://edwyna.com/openapi.yaml
MCP server: https://edwyna.com/mcp
MCP Registry metadata: https://edwyna.com/server.json
Base URL: https://edwyna.com
Authentication: Authorization: Bearer EDWYNA_API_KEY

For MCP-compatible clients, connect to https://edwyna.com/mcp. The client discovers OAuth automatically. The user signs in to a verified Edwyna account and approves permissions; do not ask the user to paste an Edwyna API key into the MCP client. MCP exposes the same prepare, send, status, list, balance, pricing, and optional transmitted-PDF operations described below.

Required workflow:
1. GET /v1/balance if balance:read is available.
2. Confirm that enough available Edwyna credit covers the quote, then POST one PDF and destination to /v1/fax-drafts. This prepares and quotes; it does not charge or send. Preparation attempts and active drafts are rate-limited.
3. Present the normalized destination, PDF page count and SHA-256 fingerprint, and exact price to the user.
4. Obtain approval before POST /v1/fax-drafts/{fax_id}/send. This deducts $4 and queues an external fax.
5. Use a unique Idempotency-Key of 16-255 characters. Reuse the same key only when retrying the same intended send.
6. Retain fax_id and GET /v1/faxes/{fax_id} until delivered or failed.
7. Optional: After delivery, GET /v1/faxes/{fax_id}/transmitted-document to save the application/pdf response when the user wants it.

Safety rules:
- Never guess a fax number, recipient identity, missing document, or user authorization.
- Never put an API key in a prompt, URL, PDF, public log, or source file.
- Never report ready, queued, submitted, or transmitting as delivered.
- Treat the transmitted PDF as the fax backend's representation of the submitted pages, not proof of what the receiving machine printed.
- An eligible failed fax restores Edwyna account credit; it does not refund the original payment method.
- Edwyna does not prepend a cover sheet. If needed, the caller must make it page one of the PDF.