Skip to main content
A test of a fax API or fax server can end with a check on Faxbeep: send a page to a test number, then poll the API until the page arrives. Polling means repeating the same request at an interval until the result appears. The scripts on this page do the polling only. Send the fax yourself with your fax provider, fax server, or machine.

How it works

1

Note the time

Just before you send, record the time in UTC, with Z:
2

Send the test

Send your test fax to a test number from your provider or machine. A scan to email test works the same way.
3

Poll for the result

Run one of the scripts below. It requests GET /api/faxes?since=... every 15 seconds, with the same since each time.
4

Check the result

The script prints the oldest matching test after since as JSON and exits with status 0. Check its page_count, open its view_url, or download its pdf_url. If no test matches before the timeout, the script exits with status 1.

Polling script

Set these environment variables, then run the script. Set FROM only if your sender ID reaches Faxbeep and nobody else uses it. Most faxes sent over a phone line arrive without a sender ID. Without FROM, set PAGES, because other people send tests at the same time. Even then, the script returns the first candidate that matches, which can be someone else’s test. Check the result before you rely on it.
Run it, for example: SINCE=2026-10-01T14:25:00Z PAGES=2 node wait-for-fax.mjs.

Writing your own client

  • Keep since fixed at the time you recorded. Don’t move it to the newest received_at you have seen. received_at is the arrival time, and a test appears only once processing finishes, so a long fax can appear after a newer, shorter one.
  • Wait between requests. The examples poll every 15 seconds; a fax usually appears within a minute after the call ends, so polling more often gains little. The rate limit is 60 requests per minute per IP address, and parallel jobs on one runner share it.
  • Set a timeout. Don’t poll indefinitely. The examples stop after 10 minutes; choose a value that suits your test.
  • On 429, wait. Wait the number of seconds in the Retry-After header, then try again.
  • Request up to 100 tests. The response is newest first, so if many tests arrive after yours, yours can drop out of it. The scripts request the maximum, limit=100, which lowers that risk but can’t remove it.
Your test is public for 30 days, like every test. Use a test page with no personal or confidential information.

Next steps

Find your fax

Make a single request by time, sender, or email address.

API reference

Rate limit, errors, and response fields.