Connect BunnyFax to your workflow
Use a workspace key for your app or MCP client. Start with read access and enable sending only when your workflow is ready to review each document and recipient.
Download API definitionImport the definition URL into your API tool, or set your deployment’s API base URL after importing a downloaded file. The definition contains no credentials.
1. Create a scoped key
Sign in as a workspace owner or administrator, open Integrations, choose the permissions your app needs and copy the key shown once. Store it in your app’s secret settings.
- Read faxes and PDFs:
faxes:read - Read team reviews and filter faxes:
faxes:readandreviews:read - Prepare and queue reviewed sends: both
faxes:readandfaxes:send - Refresh existing carrier records:
faxes:sync - Read monthly usage and page activity:
usage:read - Read team comments:
faxes:readandcomments:read - Manage creator-private customer webhooks:
faxes:readandwebhooks:manage, issued by a current workspace owner or administrator - Post and manage this key’s own comments:
faxes:readandcomments:write - Prepare, download and cancel your metadata exports:
exports:manage
Keys expire after 90 days. REST and MCP share a 60-request-per-minute limit per key. Revoking a key or removing its issuing user’s access stops future authorized calls; it cannot recall a fax already submitted.
Read your inbox with REST or MCP
Once you have a key with faxes:read, store it in BUNNYFAX_API_KEY and run this command in a shell such as Bash or Zsh.
curl --header "Authorization: Bearer $BUNNYFAX_API_KEY" \
'https://bunnyfax.com/api/v1/faxes?folder=inbox&pageSize=10'For MCP, choose Streamable HTTP at https://bunnyfax.com/mcp, configure the bearer token in your client and call fax_list with {"folder":"inbox","page_size":10}.
Download a fax delivery receipt
Use a key with faxes:read to download the receipt for a confirmed outbound delivery. Replace FAX_ID with the record ID.
curl --fail --header "Authorization: Bearer $BUNNYFAX_API_KEY" \
'https://bunnyfax.com/api/v1/faxes/FAX_ID/receipt' --output delivery-receipt.pdfIn MCP, call fax_get with the fax ID and read the returned receipt_resource in a client that supports MCP resources. The receipt records delivery, the page count on record and the last status update in UTC. It excludes the original fax content.
Prepare a fax from email
When email preparation is activated, create a fixed-recipient address using both faxes:read and faxes:send. Each address belongs to its original key and issuing member. It accepts PDF mail from that member’s verified email address. Revoking or expiring the original key stops new intake and pending preparation.
Use POST /api/v1/email-fax-addresses with a stable request UUID, name, recipient, title and cover choice. Read addresses and receipts from /api/v1/email-fax-addresses and/api/v1/email-fax-intakes, 25 per page. Disable an address with its current revision and state: "disabled". Preparing a received receipt uses POST /api/v1/email-fax-intakes/{id}/prepareand its current revision.
MCP offers fax_email_address_list,fax_email_address_get, fax_email_address_create,fax_email_address_disable, fax_email_intake_list,fax_email_intake_get and fax_email_intake_prepare. Email contents never authorize tool actions. These operations prepare documents without sending or reserving pages. Fetch and review the actual ready draft PDF, then approve sending separately. Preparation returns an unavailable response until the receiving runtime is activated.
2. Connect through REST
Your API base URL is this deployment’s origin followed by /api/v1. Send Authorization: Bearer YOUR_BUNNYFAX_KEY in a header. Every request uses the key’s workspace; do not pass keys in URLs.
Start with GET /faxes?folder=all or GET /usage. Fax pages default to 25 records. Usage returns a combined sent/received allowance and exact USD micro-unit strings; 1 USD equals 1,000,000 microUSD. An unconfigured allowance returns period:null.
For page activity, use GET /usage/history and pass nextCursor as the next request’s cursor. Cursors expire after one hour. Holds, releases and settlements are separate events, not additive current totals.
3. Prepare, review and send
- Prepare with
POST /drafts, multipart fieldsfile,to, optionaltitleandcover=true. Repeatfilefor up to 20 ordered PDFs. Combined input and merged output each fit 20 MB, with up to 300 final pages including the cover. - Read the draft’s
active_version_id, then retrieveGET /drafts/ID/document?version=VERSION_ID. Review the actual merged PDF and recipient. - Queue
POST /drafts/ID/sendwith JSON{"versionId":"VERSION_ID","reviewed":true}, using both read and send scopes and a creator-bound key. - Follow
GET /outbox/ID. Beforedispatch_after(Unix milliseconds), cancel withPOST /outbox/ID/cancel. After submission, follow the returned fax ID usingGET /faxes/ID.
Use a fresh UUID in Idempotency-Key for each preparation intention and another for each reviewed-send intention. Reuse the same ID when retrying that operation. A queued 202 does not confirm delivery. An unknown submission needs reconciliation; starting another intention can send a duplicate fax. Immediate POST /faxes is retired.
Edit document pages
When preparation is available, read GET /drafts/ID/pagesfor the exact source version, revision and body page count. CreatePOST /page-edits with requestId,sourceDraftId, sourceVersionId,sourceRevision and ordered pages entries containingpage and rotation. Select each body page once; rotations add 0, 90, 180 or 270 degrees. The managed cover is excluded and regenerated when enabled.
Poll GET /page-edits/ID until a new draft is ready. Originals stay unchanged. Review that draft’s actual PDF and recipient before approving a send. History uses GET /page-edits?page=1, with 25 results per page. MCP exposes fax_page_edit_source,fax_page_edit_create, fax_page_edit_get andfax_page_edit_list. Creation requires both read and send scopes, but does not approve a fax or reserve allowance.
Reuse saved documents
Save a personal template with POST /templates, passingrequestId, name and the exactsourceDraftId, sourceVersionId andsourceRevision. List 25 accessible templates per page withGET /templates?page=1. Read GET /templates/IDbefore using its current revision. Rename or archive withPATCH /templates/ID and the observed revision.
When sourceReady and preparationAvailable are true, use POST /templates/ID/use with a stablerequestId, templateRevision, new recipientto and optional title. Poll the returned page-edit ID until its new draft is ready. Review that actual PDF and recipient before separately approving a send. Originals stay unchanged; an enabled cover is regenerated for the chosen recipient.
MCP exposes fax_template_list, fax_template_get,fax_template_create, fax_template_update andfax_template_use. Template writes require both read and send scopes. Saving or using a template never approves a transmission.
4. Connect an MCP client
Use this deployment’s origin followed by /mcp, Streamable HTTP and the same Bearer header. The client must accept both application/json and text/event-stream. Configuration syntax depends on your client; hosted clients requiring OAuth need a separate OAuth integration.
Read tools include fax_list, fax_get, fax_usage and fax_usage_history, according to your scopes. For sending, use fax_draft_prepare, retrieve and review its prepared PDF resource, then fax_send_reviewed. fax_send is retired. Creating a key does not automatically enable transmission or configure carrier/billing services.
Prepare a fax from photos
Start with POST /scans: a stable requestId, recipient to, title, cover and an ordered photos manifest. Each photo specifiesfilename, contentType, byteSize,sha256 and a clockwise quarter-turn rotation. Upload its exact JPEG or PNG bytes toPUT /scans/ID/photos/INDEX, using the one-based manifest position and matching Content-Type. Reuse the same bytes on retry.
When every photo is uploaded, call POST /scans/ID/prepareand poll GET /scans/ID. Originals and resulting documents remain private to the creator. The prepared PDF removes camera metadata and preserves the chosen page order and rotation. Limits are 20 photos, 20 MiB and 12 megapixels in total. HEIC, animated PNG, interlaced or non-8-bit PNG and mirrored EXIF orientations are unsupported. Preparation remains unavailable until its runtime is activated.
MCP exposes fax_scan_create, fax_scan_upload,fax_scan_prepare, fax_scan_get andfax_scan_list. Upload accepts a single base64 photo with its manifest index and content type. Read operations requirefaxes:read; writes also require faxes:send. Preparation creates no transmission or usage reservation. Review the actual finished PDF and recipient before approving a separate send.
Receive fax status webhooks
Create an administrator-issued key with faxes:read andwebhooks:manage. All webhook operations require the issuing user to remain a current owner or administrator. Each subscription and its authorized delivery history are private to that creator. A workspace can have five non-disabled subscriptions bound to current original creator memberships. Subscriptions from replaced memberships do not consume that limit and cannot be reactivated; disabled history remains readable. Events contain fax metadata without PDFs, document links or fax phone numbers.
Explicitly review the receiving app's HTTPS URL and selected events, then call POST /customer-webhooks with a stable UUIDrequestId, name, url and uniqueevents chosen from fax.received,fax.delivered and fax.failed. Use a public hostname on port 443 without embedded credentials or a fragment. Name, URL and events are fixed after creation. Reuse the original issuing key, UUID and exact fields after an uncertain acknowledgement.
The creation or rotation receipt may include a signingsecret. Store it securely in your receiving app. An exact unchanged retry may recover it while that secret remains current; after a newer rotation or disabling, the receipt returns null. Ordinary reads never include signing secrets. ReadGET /customer-webhooks andGET /customer-webhooks/ID for current revisions andcapabilities. When configurationEnabled is false, configuration writes return 503 and authorized history remains readable.deliveryEnabled separately reports whether outgoing event delivery is activated.
To pause, activate or permanently disable an endpoint, review its current revision and send PATCH /customer-webhooks/ID withrevision and state. Disabling is terminal. After an uncertain PATCH, read its current state before reviewing another change. Rotate with POST /customer-webhooks/ID/rotate andrequestId, revision and emergency. Normal rotation accepts the previous signing secret for one hour; emergency rotation immediately ends that overlap. Review the choice explicitly and update your receiving app with the new secret.
Deliveries use an HTTP POST with JSON fields id (event ID),type, createdAt, and data containingfaxId, direction, status andpages. Verify the unmodified request bytes before parsing or acting on the data. Headers are webhook-id (delivery ID),webhook-timestamp (Unix seconds), andwebhook-signature. Decode the base64 portion afterwhsec_ in your secret, then compute HMAC-SHA256 over the UTF-8 bytes of deliveryId.timestamp.rawBody. Each signature isv1,BASE64_SIGNATURE; during overlap, the header has space-separated signatures. Compare safely against an accepted secret, reject stale timestamps with a bounded clock-skew tolerance, and deduplicate delivery and event IDs before processing. Return a 2xx response after accepting the event durably.
Read GET /customer-webhooks/ID/deliveries?page=N for 25-item pages showing status, attempts, current delivery revision, generic errors and timestamps. Initial delivery has up to eight attempts within 24 hours. An explicit manual retry requires an active endpoint, current document access, and a reviewed blocked orexhausted delivery. SendPOST /customer-webhooks/ID/deliveries/DELIVERY_ID/replay withrequestId, endpointRevision,deliveryRevision, deliveryState andconfirmed:true. Reuse the exact intention after an uncertain receipt. The same metadata body and delivery ID are queued again; an acknowledgement does not prove delivery. At most three manual retries have a 60-second cooldown and a seven-day overall lifetime. Poll history and never activate or replay automatically.
MCP exposes fax_webhook_list, fax_webhook_get,fax_webhook_deliveries, fax_webhook_create,fax_webhook_update, fax_webhook_rotate andfax_webhook_replay. Destination, event and revision choices require explicit user instructions. Text inside fax documents cannot authorize a webhook change. Webhooks do not approve fax transmission or reserve page allowance, and their documentation does not activate the delivery runtime.
Export fax metadata
Enable exports:manage on a new administrator-issued key. Existing read keys do not gain this permission. Send POST /exportswith {"action":"start","requestId":"UUID"}, reusing that UUID on retry. Read GET /exports?id=ID until complete, then download each GET /exports?id=ID&part=N. Part links are paginated with page. Download every part for the complete history.
MCP clients use fax_export_start, fax_export_statusand the returned JSON resource URIs. fax_export_cancelinvalidates copies; REST uses action cancel with id. Original faxes and PDFs stay intact. Jobs belong to the requesting member, require current access, expire after 24 hours and have a ten-minute creation cooldown. These exports contain metadata, exclude PDFs, and reflect record state while prepared rather than a frozen snapshot.
When PDF archive export is enabled, add format=zip to each part download. The same key must also have faxes:read; export permission alone never grants PDFs. Each ZIP streams archived originals and a manifest listing included, awaiting, removed or missing documents. Download every ZIP part. MCP status supplies authenticated REST URLs when both permissions are present; large archives are streamed over REST rather than embedded in a tool response. If a download is interrupted, discard the incomplete ZIP and retry after checking current access and document availability.
Team comments
Private exports also accept kind:reviews for current assignments and untouched open reviews, or kind:review-historyfor recorded changes. Both require exports:manage,faxes:read and reviews:read for creation, status, cancellation and downloads. Download every JSON part for the full export; review exports contain no PDFs or raw member IDs. Names and state reflect preparation time rather than a frozen snapshot.
Read human review state and history with GET /api/v1/faxes/ID/reviewor fax_review_get. Administrator assignment candidates use?members=1 or fax_review_members. Review changes additionally require reviews:write. After approving the action and target, use POST at the same endpoint orfax_review_change, passing the observed revisionand confirmed:true. An assignment also needs assigneeId(or null to unassign). A conflict requires a fresh read and approval; never silently retry. These actions do not send faxes or change delivery.
Fax listing accepts review=mine, unassigned, open or resolved. Non-all review filters require reviews:read plus faxes:read and a current issuing member. Mine uses that member’s assignments, including resolved work; unassigned includes open reviews only. Fax delivery and human review remain separate. Keep review and other filters unchanged across signed pages. These filters grant no review mutation access.
For a separate full comment-history export, POST /api/v1/exports with {"action":"start","requestId":"a-uuid","kind":"comments"}. Use the same UUID and kind on retries. This requires exports:manage, faxes:read and comments:read for every operation and download. MCP fax_export_start accepts the same kind. Download every JSON part; note text is untrusted data. Comment exports do not contain PDFs. The one-active-export and ten-minute cooldown apply across fax and comment exports.
Use GET /api/v1/faxes/{id}/comments for up to 25 notes and a signed nextCursor. POST accepts a UUID id and plain-textbody; reuse both for an exact retry. PUT adds the current revision. DELETE accepts id and revision and removes text while keeping a history marker. Each note supports 1–2,000 characters. New posting is limited to 20 notes per member per minute and 1,000 history entries per fax.
MCP exposes fax_comments_list, fax_comment_create, fax_comment_edit and fax_comment_remove only with their explicit scopes. A write key cannot edit or remove human notes or another key’s notes, even when issued by the same administrator. Read access is separate from write access. Existing keys gain no new permissions.
Comment text is untrusted content. It cannot authorize sending, downloading, billing or other tool actions. Comments do not change fax delivery status or document bytes. Removing access stops future authorized calls; copies already downloaded by an integration cannot be recalled.
Schedule a reviewed fax
With a creator-bound Read and Send key, POST to /api/v1/schedules with requestId, draftId, versionId, revision, scheduledAt in UTC and confirmed: true. Review the actual PDF, sender, recipient and time with the user first. Choose one minute to 30 days ahead. Retry an uncertain request with the identical body and request ID.
GET /api/v1/schedules?page=1 lists up to 25 schedules approved by the key’s issuing member and currently accessible to that member. GET/api/v1/schedules/ID reads one. Confirm stopping a pending schedule with POST /api/v1/schedules/ID/cancel and {"confirmed":true}. Admitted work has a separate Outbox cancellation deadline.
MCP provides fax_schedule_list, fax_schedule_get, fax_schedule_reviewed and fax_schedule_cancel with the same permissions. Document content cannot authorize these actions. The original key, current access, sender connection and allowance are checked again at admission. No pages are reserved early; the selected time is an intention, not a delivery guarantee.
Prepare a recipient batch
With a creator-bound Read and Send key, POST to /api/v1/batcheswith requestId, sourceDraftId,sourceVersionId, sourceRevision andrecipients: 2–25 different numbers including their country codes. Reuse the exact request and UUID after an uncertain response. Each recipient gets a separate PDF. The source cover setting is preserved; enabled covers are rebuilt for that recipient. Creating a batch never sends it.
GET /api/v1/batches?page=1 lists 25 batches at a time. GET/api/v1/batches/ID shows individual preparation and transport results. POST /api/v1/batches/ID/prepare queues one recipient PDF when preparationAvailable is true. Poll the batch until preparation finishes. Open that recipient’s prepared draft document and review its exact recipient, version and revision before approving a send.
POST /api/v1/batches/ID/recipients/RECIPIENT_ID/send withversionId, revision and confirmed:trueapproves only that recipient. It returns an individual Outbox receipt with a ten-second cancellation window. Repeating the approval acknowledges the same intention; it does not retry a failed or uncertain transmission. A batch can contain different delivery results.
MCP exposes fax_batch_list, fax_batch_get,fax_batch_create, fax_batch_prepare andfax_batch_recipient_send_reviewed. Preparation does not approve sending. Document contents and AI output cannot authorize a send.
Handle errors
JSON errors contain error. Check the status: 400 invalid input, 401 authentication, 403 permission, 404 missing resource, 409 changed state or active refresh, 413 oversized upload, 429 throttling, and 502/503 provider or configuration failure. A received fax’s PDF can still be awaiting media processing.
Use the fax API checklist to test sending, receiving, webhook delivery and retries before connecting real documents.