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.
SINCE=2026-10-01T14:25:00Z PAGES=2 node wait-for-fax.mjs.
Writing your own client
- Keep
sincefixed at the time you recorded. Don’t move it to the newestreceived_atyou have seen.received_atis 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-Afterheader, 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.
Next steps
Find your fax
Make a single request by time, sender, or email address.
API reference
Rate limit, errors, and response fields.
