Fax API — Send and Track Faxes Over REST
Send FAX Mail exposes a REST API so your own software can send a fax, check its status, and read your numbers without a person touching the dashboard. You authenticate with a bearer key, POST a recipient number and a document — either inline base64 or a public link — and get back a JSON fax object with an id you can poll. Posting with an Idempotency-Key makes a retried request safe, so a dropped connection never sends the same page twice. The API is part of the Business and Enterprise plans, and a key is created in a few clicks at /dashboard/developers, shown to you once.
Plan requirement
The REST API is included on the Business ($79.99/mo) and Enterprise ($169.99/mo) plans. Keys created on a lower plan are blocked at request time with a 403 plan_upgrade_required until you upgrade, so there is no quiet half-working state.
How it works
Every request carries an Authorization: Bearer header with a key that begins sfm_live_. The key is hashed before it is stored, so it is displayed exactly once when you generate it and never again. To send, you POST to /v1/faxes with the recipient in `to` and the file in a `document` object as base64, or hand over a public HTTPS `document_url` and the server fetches it for you behind an SSRF guard. The response is a fax resource with an id, a status, and the page count; a follow-up GET on /v1/faxes/:id returns the latest status as Telnyx reports it back. Each key carries scopes (faxes:send, faxes:read, numbers:read) so a send-only key cannot read history, and sends are rate limited per key.
What you can do
- ✓POST /v1/faxes to send a fax from inline base64 or a public document_url
- ✓GET /v1/faxes/:id to poll a single fax's delivery status and page count
- ✓GET /v1/faxes to list your account's faxes, newest first, with page and limit paging
- ✓GET /v1/numbers to read the fax numbers provisioned on your account
- ✓Scope a key to faxes:send, faxes:read, or numbers:read and revoke it any time
- ✓Pass an Idempotency-Key on a send so a retry returns the original fax instead of dialing twice
Setup steps
- 1Confirm your account is on Business or Enterprise — the API forms are hidden on lower plans
- 2Open /dashboard/developers and create an API key, choosing the scopes the integration needs
- 3Copy the key once at creation; it is hashed server-side and cannot be shown again
- 4Send your first fax: POST /v1/faxes with an Authorization: Bearer header, a `to` number, and a `document`
- 5Store the returned fax id and poll GET /v1/faxes/:id, or register a webhook to be told when it finishes
- 6Add an Idempotency-Key header to every send so network retries never duplicate a fax
Example
POST /v1/faxes
Authorization: Bearer sfm_live_xxxxxxxx
Idempotency-Key: order-4815-attempt-1
Content-Type: application/json
{
"to": "+15551234567",
"document": {
"content": "JVBERi0xLjQK...base64-pdf...",
"content_type": "application/pdf"
}
}Fax API — FAQ
Send an Authorization header of the form Bearer sfm_live_ followed by your key. Generate the key at /dashboard/developers; it is hashed before storage, so copy it at creation because it is shown only that one time. A request with no key, or a key that was revoked, comes back as a 401.
Yes. Put a public HTTPS link in a `document_url` field instead of an inline `document`, and the server fetches the file for you through an SSRF guard before faxing it. That avoids base64-encoding a large PDF in your request. If you would rather send the bytes directly, use the `document` object with base64 content and a content_type.
It guards against a retry sending the same fax twice. When you POST with an Idempotency-Key and the connection drops before you read the response, resending the identical request returns the fax that was already created rather than dialing the recipient again. Use a fresh key per distinct fax and reuse it only for retries of that one send.
Sends are rate limited per API key. If you exceed the window the call returns a 429 with a retry-after hint, so back off and resend after that interval. For high-volume runs, space out requests or queue them rather than firing the whole batch at once.
The REST API is a Business and Enterprise feature, and the gate is keyed on the key owner's current plan. If the account is on Starter or Professional, every v1 route answers 403 until you upgrade to Business or Enterprise. Revoking and deleting keys stays open on any plan so a downgraded account can still clean up.
Build with the Fax API
API access and webhooks are included on the Business and Enterprise plans. Create a key at /dashboard/developers and start sending.
7-day free trial · No credit card required