Node.js quickstart

Outcome

You will send a fax to a sandbox magic number, poll for its status, receive a webhook event, and verify the HMAC signature. Everything runs against the sandbox. No real faxes are sent and no credits are charged.

Prerequisites

A mintfax sandbox API key (mfx_test_...). Sign up here if you do not have one.
Node.js 18 or later (for native fetch and crypto).
A PDF file to fax. Any single-page PDF works.
A publicly reachable URL for webhooks, or a tunnel tool such as ngrok.

Step 1: Send a fax

Post a fax to the sandbox success number +15005550001. This number always delivers on the first attempt. Create send-fax.mjs:

import { readFileSync } from "node:fs";

const API_KEY = "mfx_test_abc123def456";
const BASE_URL = "https://api.mintfax.com/v1";

const file = readFileSync("document.pdf");
const form = new FormData();
form.append("to", "+15005550001");
form.append("file", new Blob([file], { type: "application/pdf" }), "document.pdf");

const response = await fetch(`${BASE_URL}/fax`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: form,
});

const fax = await response.json();
console.log(fax);
// { id: "9c1a2b3d-...", status: "queued", to: "+15005550001", created_at: "..." }

Run it:

node send-fax.mjs

Verify: The response status is 201 and the status field is queued. Save the returned id for the next step. The Idempotency-Key header makes this request safe to retry. If the network drops and you re-run the same script, mintfax returns the original response without sending a duplicate fax. See Idempotency keys for details.

Step 2: Check fax status

Poll GET /fax/{id} until the fax reaches a terminal state (delivered or failed). Create check-status.mjs:

const API_KEY = "mfx_test_abc123def456";
const BASE_URL = "https://api.mintfax.com/v1";
const FAX_ID = process.argv[2]; // pass the fax ID as a CLI argument

async function poll() {
  for (let i = 0; i < 30; i++) {
    const res = await fetch(`${BASE_URL}/fax/${FAX_ID}`, {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });
    const fax = await res.json();
    console.log(`${fax.status} (attempt ${i + 1})`);

    if (fax.status === "delivered" || fax.status === "failed") {
      console.log(JSON.stringify(fax, null, 2));
      return;
    }
    await new Promise((r) => setTimeout(r, 2000));
  }
  console.log("Timed out waiting for terminal state.");
}

poll();

Run it with the fax ID from step 1:

node check-status.mjs fax_8aZqRm4yT3vK7pNxJ2bH9c

Verify: The sandbox success number delivers within seconds. You should see delivered printed to the console.

Step 3: Receive a webhook event

mintfax sends a fax.delivered or fax.failed event to your webhook URL when a fax reaches a terminal state. The server below listens for these events and verifies the HMAC signature before trusting the payload. Create webhook-server.mjs:

import { createServer } from "node:http";
import { createHmac, timingSafeEqual } from "node:crypto";

const SIGNING_SECRET = "whsec_3JzE9rYNm2VbQ8P6KxLf1WdGa4Tc";
const PORT = 4242;

const server = createServer((req, res) => {
  let body = "";
  req.on("data", (chunk) => (body += chunk));
  req.on("end", () => {
    const timestamp = req.headers["mintfax-timestamp"];
    const signature = req.headers["mintfax-signature"];

    // Verify the signature before trusting the payload
    const expected = createHmac("sha256", SIGNING_SECRET)
      .update(`${timestamp}.${body}`)
      .digest("hex");

    const valid = timingSafeEqual(
      Buffer.from(expected),
      Buffer.from(signature)
    );

    if (!valid) {
      console.error("Signature verification failed.");
      res.writeHead(400);
      res.end("Invalid signature");
      return;
    }

    const event = JSON.parse(body);
    console.log(`Received ${event.type} for fax ${event.data.id}`);
    console.log(JSON.stringify(event, null, 2));

    res.writeHead(200);
    res.end("ok");
  });
});

server.listen(PORT, () => console.log(`Listening on port ${PORT}`));

Start the server, then expose it with ngrok (or any tunnel):

node webhook-server.mjs &
ngrok http 4242

Copy the ngrok HTTPS URL and register it as your environment’s webhook endpoint in the mintfax dashboard or via the API. Send another fax (step 1). The event arrives within seconds of delivery. Verify: The console prints Received fax.delivered for fax <id> and the signature check passes. The Webhook signing guide covers replay protection, secret rotation, and signature verification in other languages.

Step 4: Handle errors

Swap the destination number in send-fax.mjs to trigger different outcomes:

Number	Behavior
`+15005550001`	Always succeeds on first attempt
`+15005550002`	Returns busy on every attempt
`+15005550005`	Always fails permanently

The fax record’s error_code and error_message fields tell you what went wrong and whether a retry makes sense. See the Error catalog for every error code and its recommended action. The Sandbox guide lists all magic numbers and the scenarios they simulate.

Verify

You have now:

Sent a fax with POST /fax and an idempotency key.
Polled for status until delivery.
Received a webhook event and verified its HMAC signature.
Triggered error scenarios with sandbox magic numbers.

Everything above ran in the sandbox. To send real faxes, swap your sandbox key for a live key (mfx_live_...), purchase credits, and use a real fax number as the destination.

What to do next

Webhook signing - replay protection, secret rotation, and verification in other languages.
Idempotency keys - how keys are stored and matched, TTL behavior, and retry best practices.
Error catalog - every error code, its trigger, and the recommended action.
Events schema - all event types and their payload shapes.
Sandbox - magic numbers, simulated failures, and sandbox behavior.

Sending Faxes

Tracking Delivery

Going to Production

Integrations

Migration

Node.js quickstart

Outcome

Prerequisites

Step 1: Send a fax

Step 2: Check fax status

Step 3: Receive a webhook event

Step 4: Handle errors

Verify

What to do next

​Outcome

​Prerequisites

​Step 1: Send a fax

​Step 2: Check fax status

​Step 3: Receive a webhook event

​Step 4: Handle errors

​Verify

​What to do next

Outcome

Prerequisites

Step 1: Send a fax

Step 2: Check fax status

Step 3: Receive a webhook event

Step 4: Handle errors

Verify

What to do next