Back to developer docs

FaxDrop API

Developer Changelog

API changes that can affect developers, MCP clients, automation, rate limits, status polling, and integration behavior.

Subscribe via RSS

2026-09-09

Recipient-requested destination restrictions

Live fax send routes and MCP clients

What changed
Live sends check private recipient-requested restrictions before reserving credits and again before carrier submission.
Behavior impact
Blocked destinations return HTTP 403 with error_type destination_blocked. A late block follows the existing reservation rollback path. Already submitted faxes and carrier retries are unaffected. Sandbox sends do not transmit and remain synthetic.
Action needed
Do not retry this destination. Contact the recipient for another submission option. Restrictions fail open when the lookup is unavailable, so they are not a continuous delivery-blocking guarantee.

2026-08-27

Tighter overnight ceiling on free-tier sends

POST /api/send-fax and MCP clients

What changed
The platform-wide free-tier ceiling introduced on 2026-08-25 is now time-of-day aware. It is lower during overnight hours in US Eastern and unchanged during the rest of the day. The window is evaluated per request against the America/New_York IANA zone, so it holds the same local boundary across the daylight-saving change. The ceiling values and the exact window are operational settings and are not published.
Behavior impact
No change for API-key callers with credits or an active subscription: those sends are never subject to the platform-wide ceiling, and no request field, response field, header, status value, or per-key rate limit changed. A caller sending on the free tier (no credits and no active plan) can now receive 429 with a Retry-After during overnight US Eastern hours after far fewer platform-wide sends than before. The 429 body is the existing rate-limited error shape, and it may carry no X-RateLimit-* headers at all; any that are present describe only your per-key quota, which can still be unspent.
Action needed
If your integration sends on the free tier and runs overnight in US Eastern, expect 429 sooner and honor the Retry-After header, which points at the next reset. Do not treat the per-key send_fax limit of 30 per hour as guaranteed free-tier throughput; the platform-wide ceiling can refuse a send well before it, and do not derive throughput from the X-RateLimit-* counters on a 429. Hold credits or an active plan for uninterrupted throughput at any hour.

2026-08-25

Free-tier send abuse controls hardened

POST /api/send-fax and MCP clients

What changed
Free-tier sends are now subject to a platform-wide ceiling applied per clock hour across all callers, and the per-source-address limits are claimed atomically before the carrier call rather than counted after it. Requests that are declined for insufficient credits or page limits still do not consume any rate-limit quota.
Behavior impact
No change for API-key callers with credits or an active subscription: the send_fax key rate limits (10/minute, 30/hour, 500/day) and every request and response field are unchanged, and those sends are never subject to the platform-wide ceiling. A free-tier caller can now receive 429 with a Retry-After when the platform-wide ceiling is in effect. Corrected 2026-08-27: this entry originally said the X-RateLimit-* headers would still show per-key quota remaining on that 429. They are in fact not attached to a platform-wide 429 at all, and any counters you do see describe only your per-key quota. Honor Retry-After rather than the counters. The 429 body uses the existing rate-limited error shape.
Action needed
Honor the Retry-After header rather than the X-RateLimit-* counters when handling a 429, since the platform-wide ceiling can fire while your per-key quota is unspent. If your integration sends on the free tier, hold credits or an active plan for uninterrupted throughput.

2026-08-18

Clarified the send-and-status lifecycle

/for-developers, llms.txt, agent prompt, and MCP guidance

What changed
Developer guidance now leads with one POST to start a send and one GET to retrieve the clearest current supported status. It calls out unknown as a valid status when final carrier evidence is unavailable, requires polling with backoff, and clarifies that every signed-in account can generate API keys using the same credits as browser sends.
Behavior impact
None. No API request, response, authentication, pricing, credit, fax, status, or polling behavior changed.
Action needed
Treat unknown as unresolved rather than queued, completed, or failed. Continue bounded polling with backoff, and do not resubmit a send after receiving a faxId.

2026-08-11

Support contact standardized on hello@faxdrop.com

API error guidance, OpenAPI, /for-developers, llms.txt, and MCP clients

What changed
Customer and developer support guidance now consistently directs questions and incident reports to hello@faxdrop.com.
Behavior impact
No API request, response, authentication, pricing, credit, fax, or polling behavior changed. Only the published support contact and automated support Reply-To address changed.
Action needed
Update saved support contacts from support@faxdrop.com to hello@faxdrop.com.

2026-08-11

Minimized public fax status details

GET /api/fax-status/{faxId}, GET /api/ext/fax-status/{faxId}, and hosted status pages

What changed
Both unauthenticated hosted status responses no longer return the full recipient number, raw carrier error text, carrier error code, or carrier error type. They now return customer-safe failure guidance, delivery uncertainty, page count when available, a not-found signal, and a temporary status-unavailable signal. The extension response keeps a customer-safe error summary for compatibility. The undocumented and unused /api/waitlist route was also removed.
Behavior impact
Forwarded or exposed hosted status links no longer disclose the full fax destination or raw carrier diagnostics. This does not change the authenticated /api/v1/fax/{faxId} developer contract or fax sending behavior.
Action needed
Extension and internal hosted-status clients should stop reading recipientNumber, errorCode, or errorType and use failure, statusUnavailable, and notFound. The error field, when present, is now customer-safe rather than raw carrier text. API-key integrations should continue using /api/v1/fax/{faxId}.

2026-07-08

Sandbox test keys (fd_test_)

API keys, POST /api/send-fax, GET /api/v1/fax/{faxId}, and MCP clients

What changed
You can now generate a sandbox API key with the fd_test_ prefix in the account dashboard. A sandbox POST /api/send-fax never calls the carrier and never uses credits; it returns a synthetic fdtest_ fax that is immediately completed, pollable at GET /api/v1/fax/{faxId} with the same test key. Live keys (fd_live_) and test keys are isolated: a test key cannot read live faxes and a live key cannot read sandbox faxes. Sandbox faxes expire after 24 hours.
Behavior impact
No change to live sends. Live keys behave exactly as before. Sandbox is an additive, isolated mode.
Action needed
Use an fd_test_ key to wire and test your integration without billing or real transmission, then switch to an fd_live_ key for production.

2026-07-08

Developer changelog RSS feed

/for-developers/changelog, MCP clients, and agent watchers

What changed
Added a machine-readable RSS 2.0 feed of this developer changelog at /for-developers/changelog/rss.xml, plus a compact "What's new" dropdown on /for-developers surfacing recent entries. llms.txt now links the feed.
Behavior impact
No API behavior change. New subscription surface for developer-impacting changes only.
Action needed
Subscribe to /for-developers/changelog/rss.xml to be notified of API behavior changes instead of polling the page.

2026-07-08

Published retry, backoff, and status guidance

/for-developers, llms.txt, agent-prompt, and MCP clients

What changed
Added a Reliability section to the developer docs and agent-readable copy. It documents which responses are safe to retry (transient 500 on reads/status with bounded exponential backoff; 429 and 409 after Retry-After), which are not (400/401/402, and resubmitting a send once a faxId exists), and states that POST /api/send-fax must not be auto-retried after a timeout or 500 until idempotent send retries ship. Clarifies that FaxDrop's health monitors are internal (no public status page) and incidents go to support@faxdrop.com.
Behavior impact
No API behavior change. Documentation and guidance only.
Action needed
Adopt the retry rules in your client: backoff on transient read failures, respect Retry-After, and never blind-retry a send. Poll status after a faxId is returned.

2026-07-08

Recent fax history endpoint for API keys

GET /api/v1/faxes, MCP clients, and agent-readable docs

What changed
Added a read-only GET /api/v1/faxes endpoint. With an X-API-Key header it lists your recent API-key-sent faxes (fax id, recipient number, normalized status, pages, credits used, created and completed timestamps, delivery-email preference, and a status URL). Web-UI sends are excluded. Supports a limit query parameter (default 25, max 100). No document contents are returned.
Behavior impact
No change to send or status behavior. New read surface only, using the status_poll read rate-limit policy.
Action needed
Use GET /api/v1/faxes to reconcile sends by fax id instead of relying on recipient number alone.

2026-07-08

Account balance endpoint for API keys

GET /api/v1/account/balance, MCP clients, and agent-readable docs

What changed
Added a read-only GET /api/v1/account/balance endpoint. With an X-API-Key header it returns available credits, monthly remaining, purchased credits, subscription tier with included and used credits this period, and API sends this month. It never returns raw Stripe IDs or email. Subscription state is read uid-first so API-key callers see the same subscription the send path charges against.
Behavior impact
No change to send or status behavior. The endpoint uses the status_poll read rate-limit policy. It is a new read surface only.
Action needed
Call GET /api/v1/account/balance with your X-API-Key to check credit and subscription state instead of scraping the account UI.

2026-06-25

Developer HIPAA wording narrowed to current posture

/for-developers, llms.txt, agent-readable docs, and MCP clients

What changed
Developer-facing copy now uses healthcare workflow support and signed carrier BAA wording instead of broad product-level HIPAA claims. The API contract and request or response fields did not change.
Behavior impact
No send, status, auth, rate-limit, pricing, or credit behavior changed. This is a trust-language and documentation posture update only.
Action needed
Do not market FaxDrop with broad product-level HIPAA claims from your integration unless FaxDrop later confirms broader vendor BAA coverage. Use healthcare workflow support or signed carrier BAA wording.

2026-06-25

Launch destinations limited to 50 US states and Canada

POST /api/send-fax, OpenAPI, MCP clients, and agent-readable docs

What changed
FaxDrop now documents and enforces destination support in the 50 US states and Canada for launch. Other destination countries are not currently available through the send endpoints.
Behavior impact
Requests with valid destination numbers outside the 50 US states and Canada now return 400 before credit reservation or Sinch send. Existing sends to the 50 US states and Canada are unchanged.
Action needed
Send only destination numbers in the 50 US states or Canada for launch. Keep any broader international workflow behind your own feature flag until FaxDrop publishes region-aware pricing and support.

2026-06-13

Structured carrier failure fields in status polling

GET /api/v1/fax/{faxId}, OpenAPI, MCP clients, and status polling

What changed
Failed or partial status responses now include errorCode and errorType when Sinch provides structured carrier failure evidence. The existing error field remains available and may be null when Sinch only returns structured fields.
Behavior impact
Clients can distinguish document conversion failures from recipient-line failures without parsing generic text. Non-terminal and completed responses are unchanged.
Action needed
When status is failed or partial, read errorCode and errorType before falling back to error text.

2026-05-28

API-key delivered email suppression

POST /api/send-fax, terminal notifications, MCP clients, and batch senders

What changed
API-key sends can pass sendEmail=false to suppress delivered-fax confirmation emails for a specific fax. FaxDrop stores the per-fax preference on the fax status record and echoes deliveryEmail as enabled or suppressed in the success response.
Behavior impact
The default remains sendEmail=true. Consumer web sends keep delivered emails enabled. Failed-fax emails, status pages, refunds, and operator alerts still run. Status polling and reconcile treat the suppressed delivered email as satisfied so healthy completed faxes do not stay pending.
Action needed
Batch API clients that rely on status polling for audit records may pass sendEmail=false. Clients that want email confirmations should omit the field or pass sendEmail=true.

2026-05-26

Developer API reliability bundle

Developer API, MCP clients, status polling, and rate limits

What changed
FaxDrop aligned terminal success on completed, split API-key send and status polling limits, exempted valid API-key sends from the anonymous IP cap, and added a per-fax status refresh throttle.
Behavior impact
API-key sends use the send_fax policy at 10/min, 30/hr, and 500/day. Status polling uses the status_poll policy at 60/min, 500/hr, and 2000/day. Active status polls refresh from Sinch at most once every 10 seconds per fax ID.
Action needed
Treat completed as terminal success. Treat older delivered wording as a legacy alias. Use the X-RateLimit-Policy and status freshness headers when tuning client polling.

Clear about how FaxDrop works

Healthcare workflows

Fax carrier BAA in place | Broader vendor review ongoing

Hosted checkout

Payment details are entered on Stripe's checkout

Current status

Check the latest available update after sending

Outbound only

No inbox, dedicated fax line, or installed fax software