# 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 pricing, balance, secure PDF handoff, prepare, send, status, list, delivery-record, and optional transmitted-PDF operations.

MCP PDF handoff:
- Call create_pdf_upload with the intended PDF filename.
- Give the returned browser_upload_url to the user, or PUT application/pdf bytes to upload_url. The URL is single-use and expires after 15 minutes.
- Poll get_pdf_upload_status until ready_for_prepare is true.
- Call prepare_fax with upload_id. Base64 remains available as a compatibility fallback; provide exactly one of upload_id or pdf_base64.
- Uploading alone does not prepare, charge, or send a fax.

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. After delivery, GET /v1/faxes/{fax_id}/delivery-record to save Edwyna's formal application/pdf delivery record.
8. Optional: GET /v1/faxes/{fax_id}/transmitted-document to save the backend's PDF representation 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.
- A delivery record reports Edwyna's final delivered status; it does not establish that a person read, understood, or accepted the document.
- 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.