Send a Fax from Node.js — Calling the REST API
There is no official Send FAX Mail Node.js SDK on npm, and we say so plainly rather than ship a wrapper that trails the API. You call the REST API directly with the built-in fetch that ships in modern Node, or with axios if you prefer — it is a few lines. You put your bearer key in the Authorization header, POST a recipient and a document to /v1/faxes, and read the JSON fax object back. An Idempotency-Key header makes a retried request safe. The same key and endpoints back every other call, so the first working request sets the pattern for the rest.
Plan requirement
The REST API is part of the Business ($79.99/mo) and Enterprise ($169.99/mo) plans. A key created on a lower plan is refused at request time with a 403 plan_upgrade_required, so your Node code gets an explicit error instead of a quiet half-working state until you upgrade.
How it works
The API is plain JSON over HTTPS, so the fetch built into Node 18+ is enough — no dependency required. You call fetch on /v1/faxes with method POST, an Authorization header carrying a key that begins sfm_live_, and a JSON body with `to` and a `document` object (base64 content plus content_type) or a public `document_url`. The response is a fax resource with an id, a status, and a page count; a follow-up GET on /v1/faxes/:id returns the latest status. Add an Idempotency-Key header so a retry returns the original fax rather than dialing twice, and branch on the response status for 401 (bad or revoked key), 403 (plan gate), and 429 (rate limited). axios works the same way if you want interceptors or automatic JSON handling.
What you can do
- ✓POST /v1/faxes from built-in fetch or axios with a bearer key in the header
- ✓Send inline base64 with a document object, or hand over a public document_url
- ✓Poll GET /v1/faxes/:id for delivery status and page count
- ✓List recent faxes with GET /v1/faxes for a reconciliation script
- ✓Pass an Idempotency-Key so a retried POST never double-sends
- ✓Handle 401 / 403 / 429 explicitly so the process fails or backs off predictably
Setup steps
- 1Confirm the account is on Business or Enterprise so the API is active
- 2Create an API key at /dashboard/developers with the faxes:send scope
- 3Store the key in an environment variable, never committed to source
- 4Use the built-in fetch in Node 18+ (or npm install axios) — there is no Send FAX Mail package
- 5POST to /v1/faxes with the Authorization header, a `to` number, and a document
- 6Read the returned fax id and poll GET /v1/faxes/:id, or register a webhook for status
Example
import { readFile } from "node:fs/promises";
const pdf = (await readFile("invoice.pdf")).toString("base64");
const resp = await fetch("https://www.sendfaxmail.com/v1/faxes", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.SFM_API_KEY}`,
"Idempotency-Key": "invoice-4021",
"Content-Type": "application/json",
},
body: JSON.stringify({
to: "+15551234567",
document: { content: pdf, content_type: "application/pdf" },
}),
});
const fax = await resp.json();
console.log(fax.id, fax.status);Node.js Fax — FAQ
No. There is no package to install from us. The API is JSON over HTTPS, so the fetch built into modern Node calls it in a few lines, and axios works too. We prefer pointing you at the real endpoints over maintaining a wrapper that might lag the API.
Built-in fetch is enough on Node 18 and later — no dependency required to send a fax. Reach for axios only if you want features like interceptors, automatic retries, or a specific error-handling style. Either way the request shape against /v1/faxes is identical.
Attach an Idempotency-Key header with a value unique to that fax. If the request fails partway and your code retries with the same key, our API returns the fax it already created instead of dialing again. Use a new key for each distinct send and reuse one only across retries of that same send.
Register a webhook endpoint at /dashboard/developers and receive fax.delivered and fax.failed at a small Express or Fastify route that verifies the X-SFM-Signature HMAC. That beats polling for volume. For a one-off script, polling GET /v1/faxes/:id with the returned id until the status settles is simpler.
Build with the Node.js Fax
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