Fax API for developers & AI agents
One call to send. One call to know.
One authenticated POST starts the send. One authenticated GET returns the clearest current supported status, including an honest unknown when final carrier evidence is unavailable. Repeated polling with backoff may be required before the status becomes terminal.
Every signed-in account can generate API keys. API and browser sends use the same purchased and monthly included account credit balance. Pro buys included volume, not permission to use the API.
What is the FaxDrop fax API?
The FaxDrop fax API is a REST API for sending faxes from code. There is no fax machine, no fax line, and no legacy telephony stack to manage. You POST a document and a recipient number to one endpoint, and FaxDrop transmits the fax over the carrier network. When you need delivery status, you GET one endpoint with the fax ID.
Two HTTP calls cover the core lifecycle. Optional read-only endpoints expose account balance and recent API fax history. FaxDrop is built for developers who need an outbound fax from an app, script, cron job, or AI agent without provisioning an inbound fax number.
It is a real REST API, not a contact form with a slow backend. Authentication is a single X-API-Key header. Every signed-in account can generate keys. Browser and API sends draw from the same purchased or monthly included account credits.
New to sending faxes from code? Our fax API guide walks through what a fax API is, how the send-and-poll flow works, and how the credit model applies to API sends.
How it works: send and poll
Send a fax. Make a POST /api/send-fax request with a multipart form. Required fields are the document (file, as PDF, JPEG, or PNG), the recipient fax number in E.164 format, a sender name, and a sender email for confirmation. You get back a faxId immediately.
Check status. Poll GET /api/v1/fax/{faxId} with the same API key. The response tells you whether the fax is queued, sending, completed, failed, or partial. It may return unknown when final carrier evidence is unavailable. Never translate that result into queued, completed, or failed certainty.
No webhook setup is required for the core lifecycle. Poll with bounded backoff until the response is terminal or your workflow reaches its own timeout. Destinations in the 50 US states and Canada are supported today.
Read your account. Two optional read-only endpoints use the same API key: GET /api/v1/account/balance returns your available credits, monthly remaining, subscription tier, and API sends this month, and GET /api/v1/faxes lists your recent API-key faxes by ID with status and credit cost. Neither returns document contents.
Test in the sandbox. Generate an fd_test_ key in your account to integrate without sending a real fax or spending credits. A sandbox send never touches the carrier and returns a synthetic fdtest_ fax that is immediately completed. Test and live keys are isolated; switch to an fd_live_ key to send for real. Sandbox keys work only on send and single-fax status; the balance and fax-list endpoints require a live key.
Quickstart
Three steps. No SDK required.
Create an account
Sign in with Google at faxdrop.com. The free tier includes 2 free sends per month, up to 5 total pages each including the cover page. No credit card is required to start.
Generate an API key
Go to your account dashboard and open the API Keys section. Click Generate New Key. Copy the key immediately. You can create up to 3 active keys per account.
Store your key securely. It is shown once at creation. If you lose it, revoke it and generate a new one. Never commit API keys to source control.
Send a fax
POST a multipart form with the recipient number and your document. We accept PDF, JPEG, and PNG files up to 4 MB. Export Word documents as PDF first. Pass your key as an X-API-Key request header.
curl -X POST https://www.faxdrop.com/api/send-fax \
-H "X-API-Key: fd_live_your_api_key_here" \
-F "recipientNumber=+12125551234" \
-F "senderName=Your App" \
-F "senderEmail=you@example.com" \
-F "sendEmail=true" \
-F "includeCover=true" \
-F "recipientName=Dr. Jane Smith" \
-F "subject=Patient records request" \
-F "senderCompany=Acme Medical Group" \
-F "senderPhone=+13155550123" \
-F "file=@document.pdf"Use with an AI agent
NewCopy a ready-made prompt that teaches any AI assistant (Claude, ChatGPT, etc.) how to send faxes using your FaxDrop API key.
API Reference
Base URL: https://www.faxdrop.com
Authentication
All API requests require an API key passed via the X-API-Key header. API keys start with fd_live_ followed by 32 hex characters.
You can also use FaxDrop programmatically through a web session (cookie-based auth), but API keys are required for server-to-server integrations and AI agent workflows. Requests authenticated with an API key are tracked separately in your usage dashboard.
X-API-Key: fd_live_a1b2c3d4e5f6.../api/send-faxSend a fax to numbers in the 50 US states and Canada.
Request Headers
X-API-KeyRequired. Your API key. Generate one at faxdrop.com/account.Content-TypeSet to multipart/form-data (most HTTP clients set this automatically when you pass form data).Form Fields
| Field | Type | Required | Description |
|---|---|---|---|
file | File | Yes | Document to fax. PDF, JPEG, or PNG. Max 4 MB. |
recipientNumber | String | Yes | Recipient fax number in E.164 format. Destinations in the 50 US states and Canada are supported for launch. Other destination countries are not currently available through the send endpoints. Example: +12125551234 |
senderName | String | Yes | Sender name. Appears on the fax cover page. Can be your app name or a person's name. |
senderEmail | String | Yes | Email address for terminal status updates. Does not need to match your account email. |
sendEmail | String | No | API-key sends only. Defaults to "true". Set to "false" to suppress delivered-fax confirmation emails for batch workflows. Failed-fax emails, status pages, confirmed-failure credit restoration, and operator alerts still run. |
includeCover | String | No | Set to "true" to include a cover page. Defaults to no cover for paid users. Free-tier faxes always include a branded cover page. |
coverNote | String | No | Message printed on the cover page. Only used when includeCover is true. Max 500 characters. |
recipientName | String | No | Recipient's display name for the cover page. Example: Dr. Jane Smith |
subject | String | No | RE: subject line printed on the cover page. Max 200 characters. |
senderCompany | String | No | Sender's company or organization name. Displayed alongside senderName on the cover page. Max 100 characters. |
senderPhone | String | No | Sender's phone number. Printed on the cover page for recipient callbacks. Example: +13155550123 |
Success Response 200 OK
{
"success": true,
"faxId": "fax_abc123",
"deliveryEmail": "enabled"
}| Field | Type | Description |
|---|---|---|
success | Boolean | Always true on a 200 response. |
faxId | String | Unique identifier for this fax. Use this to track delivery status. |
deliveryEmail | String | Public echo of the delivered-fax email preference. Returns enabled or suppressed. Non-API sends return enabled. |
/api/v1/fax/{faxId}Check the delivery status of a fax. Poll this endpoint until the status is completed, failed, or partial.
Path Parameters
faxIdRequired. The fax ID returned from POST /api/send-fax.Request Headers
X-API-KeyRequired. Your API key. You can only check faxes sent from your own account.Status Values
| Status | Meaning |
|---|---|
queued | Fax accepted and waiting to be transmitted. |
sending | Fax is currently being transmitted to the recipient. |
completed | The carrier reported completion at the receiving fax machine. This does not prove a person read or processed the fax. pages and completedAt will be populated. |
failed | Fax delivery failed. Check the error field for details. |
partial | Some pages were delivered but the transmission was interrupted. |
unknown | FaxDrop could not currently determine the upstream status. Retry status polling with backoff. |
Success Response 200 OK
{
"id": "fax_abc123",
"status": "completed",
"recipientNumber": "+12125551234",
"pages": 3,
"completedAt": "2026-03-03T12:34:56.000Z"
}When a fax fails, the response includes carrier failure fields when available:
{
"id": "fax_abc123",
"status": "failed",
"recipientNumber": "+12125551234",
"pages": null,
"completedAt": null,
"error": "Line busy. No answer after 3 attempts.",
"errorCode": 1001,
"errorType": "CALL_ERROR"
}| Field | Type | Description |
|---|---|---|
id | String | The fax ID you queried. |
status | String | Current delivery status. One of: queued, sending, completed, failed, partial, unknown. Treat legacy delivered as completed if an older client cached that value. |
recipientNumber | String | null | The fax number the document was sent to. |
pages | Number | null | Number of pages transmitted. Populated after delivery completes. |
completedAt | String | null | ISO 8601 timestamp when the fax finished (completed, failed, or partial). Null while in progress. |
error | String | null | Error description. Only present when status is failed or partial. |
errorCode | Number | null | Carrier error code when Sinch provides one. Only present when status is failed or partial. |
errorType | String | null | Machine-readable carrier error type when available, such as DOCUMENT_CONVERSION_ERROR. |
Polling Tips
Use a bounded polling strategy that respects the published limits:
- Poll every 5 seconds for the first 2 minutes
- Then every 30 seconds for up to 10 minutes
- Stop polling once status is
completed,failed, orpartial - Keep
unknownunresolved and retry with backoff until your own timeout
Status checks use their own read-only limit bucket: 60/min, 500/hr, 2000/day. Active faxes refresh from Sinch at most once every 10 seconds per fax ID.
Example Requests
cURL
curl https://www.faxdrop.com/api/v1/fax/fax_abc123 \
-H "X-API-Key: fd_live_your_api_key_here"Python
import requests
response = requests.get(
"https://www.faxdrop.com/api/v1/fax/fax_abc123",
headers={"X-API-Key": "fd_live_your_api_key_here"},
)
data = response.json()
print(data["status"]) # "completed"Node.js
const res = await fetch(
"https://www.faxdrop.com/api/v1/fax/fax_abc123",
{ headers: { "X-API-Key": "fd_live_your_api_key_here" } },
);
const data = await res.json();
console.log(data.status); // "completed"Error Reference
All errors follow the same JSON schema.
Error responses include an error message, a machine-readable error_type, and when applicable a hint with a suggested fix and a retry_after value in seconds.
// 401 - Invalid or missing API key
{
"error": "API key not found or revoked.",
"error_type": "unauthorized",
"hint": "Check your key at https://faxdrop.com/account or generate a new one."
}
// 402 - No credits remaining
{
"error": "Insufficient credits. Please top up your account.",
"error_type": "payment_required",
"hint": "Add credits at https://faxdrop.com/pricing.",
"retry_after": 3600
}
// 429 - Rate limit hit
{
"error": "Rate limit exceeded. You are allowed 30 requests per hour.",
"error_type": "rate_limited",
"retry_after": 42
}
// 400 - Bad request
{
"error": "Unable to process your document.",
"error_type": "bad_request",
"hint": "Supported formats: PDF, JPG, PNG. Export Word documents as PDF first. Max 4 MB."
}| HTTP Status | error_type | When it happens |
|---|---|---|
400 | bad_request | Missing required fields, invalid fax number format, unsupported file type, file too large |
401 | unauthorized | Missing API key, key not found, key revoked, wrong key format |
402 | payment_required | No credits remaining, free tier exhausted. Check retry_after for when you can try again after topping up. |
429 | rate_limited | Per-key rate limit exceeded. See Rate Limits below. retry_after tells you exactly how many seconds to wait. |
500 | internal_error | Unexpected server error. These are rare. Safe to retry reads and status with backoff, but do not auto-retry POST /api/send-fax (see Reliability below). Contact support if they persist. |
Rate Limits
Send and status polling use separate fixed-window buckets per API key.
| Policy | Endpoint | Minute | Hour | Day | Response header |
|---|---|---|---|---|---|
send_fax | POST /api/send-fax | 10 | 30 | 500 | X-RateLimit-Limit / X-RateLimit-Remaining |
status_poll | GET /api/v1/fax/{faxId}, GET /api/v1/account/balance, GET /api/v1/faxes | 60 | 500 | 2000 | X-RateLimit-Limit-Hour / X-RateLimit-Remaining-Hour |
| Non-API-key web sends | POST /api/send-fax without a valid API key | - | 5 per IP | - | This web abuse guard applies to anonymous and signed-in web sends, but not valid API-key sends. |
Every successful API-key response includes X-RateLimit-* headers so you can track your quota in real time. X-RateLimit-Policy names the active policy. When you hit a limit, the response also includes a Retry-After header and a retry_after field in the JSON body.
Rejected requests (429 responses) do not count against your limit. Only successful requests consume quota.
X-RateLimit-Limit: 10 X-RateLimit-Remaining: 7 X-RateLimit-Reset: 1740924120 X-RateLimit-Limit-Hour: 30 X-RateLimit-Remaining-Hour: 29 X-RateLimit-Limit-Day: 500 X-RateLimit-Remaining-Day: 499 X-RateLimit-Policy: send_fax
Reliability: retries and status
How to handle transient errors safely, and where to check for incidents.
FaxDrop's health monitors are internal and secret-protected, so there is no public status URL to poll. For a suspected incident, email hello@faxdrop.com. Developer-impacting API changes are posted on the developer changelog (subscribe via RSS).
Safe to retry (reads and status)
- Retry a transient
500on a read or status request with bounded exponential backoff, for example 1s, 2s, then 4s, capped. - On
429or409, wait for theRetry-Afterheader (or theretry_afterbody field), then retry.
Do not retry
- Do not retry
400,401, or402until the request, key, or account state changes. The same request fails the same way. - Once
POST /api/send-faxreturns afaxId, do not resubmit. PollGET /api/v1/fax/{faxId}for the outcome. - Do not automatically retry
POST /api/send-faxafter a timeout or500. Sinch may have accepted the fax before FaxDrop returned the error, so a blind retry can send a duplicate. Safe idempotent send retries are on the roadmap.
Usage Tracking
All faxes sent via API key are logged separately from web UI faxes. Your account dashboard shows monthly API usage counts and recent activity per key. Usage data is retained for 400 days.
Credits are shared across API and web UI usage. Each fax costs the same regardless of how it was initiated. Check your pricing plan for per-fax rates.
The API uses the same credit model as the rest of FaxDrop. One purchased or subscription credit covers one outbound fax of up to 10 uploaded pages; longer documents consume one credit per 10-page upload block. Buy one credit for $1.99, or choose a credit pack or subscription for a lower per-credit rate. Web sends and API sends draw from the same balance.
Using the fax API with AI agents
FaxDrop is built so an AI agent can send a fax the same way a person does: one authenticated REST call, no browser. Point your agent at POST /api/send-fax with an X-API-Key header and it can fax PDFs, then retrieve the clearest current status with GET /api/v1/fax/{faxId}.
Agents must confirm the recipient, file, and cover details before sending. They must preserve unknown as unresolved carrier evidence, poll with backoff, and never blind-retry a send after an ambiguous timeout or server error.
If you are working in the Model Context Protocol ecosystem, the third-party community project klodr/faxdrop-mcp provides an integration for FaxDrop. FaxDrop does not operate or version that server. Review its current source, permissions, and documentation before installing it. The FaxDrop OpenAPI contract remains authoritative when community documentation differs.
Built for the outbound last mile
FaxDrop fits workflows that already have a document and recipient fax number. It focuses on starting the transmission, returning an actionable status, and keeping uncertainty explicit. Migrating an existing integration? Review the migration checklist.
Start the send
Submit a PDF, JPEG, or PNG with one authenticated multipart POST.
Check the evidence
Poll one fax ID for normalized status, including an honest unknown.
Choose your volume
Use the same API with purchased credits or monthly included account credits.
What developers are building
FaxDrop handles the fax infrastructure so you can focus on your product.
Healthcare platforms
Send prescriptions, referrals, and medical records to providers who still require fax. Verify your full workflow and compliance obligations before using any integration with sensitive data.
Legal document systems
Send court filings, signed agreements, and discovery documents to fax-only recipients. Preserve the returned status without overstating unresolved carrier evidence.
Government form automation
IRS submissions, state filings, permit applications. Many government agencies still require fax. Automate the last mile.
AI agents and workflows
Give an agent the same send-and-status lifecycle as an app. The agent must confirm before sending, preserve unknown, and follow the published retry rules. A third-party community MCP integration is available for review.
Why developers choose FaxDrop
Honest status
The normalized contract includes unknown when final carrier evidence is unavailable. Your workflow never has to invent certainty.
Plan-neutral API access
Every signed-in account can generate API keys. Pro buys included volume, not permission to integrate.
Simple REST API
POST /api/send-fax to send, GET /api/v1/fax/{id} to poll status. Optional read endpoints for account balance and fax history. Multipart form. PDF, JPEG, or PNG.
Shared credit balance
Browser and API sends draw from the same purchased and monthly included account credits. Choose one fax, a credit pack, or a monthly plan.
Agent-Ready
Built for the MCP era. Your AI agent can send faxes the same way a human does. No browser required.
Sandbox first
Use an isolated test key to exercise send and status calls without contacting the carrier or spending credits.
Fax API FAQ
What is a fax API?
A fax API lets you send and track faxes from code instead of a fax machine. You make an HTTP request with your document and the recipient number, and the provider transmits the fax over the carrier network. FaxDrop's fax API is a small REST API: endpoints to send and check status, plus read-only account balance and recent API-key fax records.
What is the best fax API for developers?
The best fax API depends on the workflow. FaxDrop fits outbound jobs that need X-API-Key auth, one POST to start a send, one GET to check its clearest current status, sandbox testing, and optional balance and fax-history endpoints. Compare any provider against your destination, compliance, support, and inbound requirements.
Is there a simple fax API?
FaxDrop's core lifecycle uses POST /api/send-fax to start a send and GET /api/v1/fax/{faxId} to retrieve its current status. Authentication uses one X-API-Key header and the document uses a multipart form. No SDK or outbound fax number is required.
How do I send a fax with an API?
Generate an API key in your account dashboard, then POST a multipart form to /api/send-fax with your X-API-Key header, the recipient number in E.164 format, a sender name and email, and your PDF, JPEG, or PNG file. You get back a faxId to track delivery.
Do I need a fax number to use the fax API?
No. You do not provision or rent a fax number to send with FaxDrop. You send to a recipient's fax number; FaxDrop handles the outbound transmission. Inbound fax numbers are a separate capability and are not part of the send API.
Can an AI agent send a fax?
Yes. An agent can call POST /api/send-fax, then poll GET /api/v1/fax/{faxId} with backoff. It must preserve unknown as unresolved carrier evidence and confirm with the user before sending. The third-party klodr/faxdrop-mcp project provides one community integration.
Is the FaxDrop fax API a Twilio Fax alternative?
FaxDrop can cover an outbound send-and-status workflow that previously used another fax API. Compare authentication, request fields, status meanings, retries, supported destinations, and pricing before migrating. See the Twilio migration guide.
Ready to integrate?
Sign in, generate a sandbox key, and test the core lifecycle without sending a real fax or spending credits.
Questions? Email us at hello@faxdrop.com or visit /support.
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