Faxbot is a proprietary, self-hosted fax platform with a web Admin Console, a REST API, cloud and SIP providers, and integrations for AI assistants. It helps organizations send and receive documents, choose delivery routes, track costs, and deliver incoming documents to the inboxes staff already use.
This README describes the current source checkout. Published packages and deployed installations may have fewer features; the roadmap distinguishes implemented capabilities from planned work and experiments.
License
New Faxbot-owned work requires prior written permission from David Montgomery for use, modification, distribution, resale, or hosting. Contact dmontg@gmail.com for permission. The setup instructions below are for authorized users. See LICENSE for the terms.
Earlier MIT releases retain their existing permissions, including material already released on public development branches. LICENSE-MIT preserves that notice; it does not license new proprietary additions. Third-party components keep their own licenses.
What Faxbot does
- Send and receive faxes. Prepare PDF, TXT, and supported TIFF documents, track outbound jobs, and organize received faxes in mailboxes. Uncertain submissions wait for confirmation instead of being blindly sent again. A received fax shows as waiting until Faxbot has fetched and checked its real document; see receiving faxes.
- Choose providers independently. Use separate outbound and inbound providers. Built-in adapters cover Phaxio, Sinch, the Telnyx Fax API, Documo, HumbleFax, eFax, SignalWire and SIP/Asterisk; supported operations vary by provider. Additional HTTP providers can use manifests. See provider setup.
- Fax through your own SIP carrier or phone system. Connect a carrier SIP trunk (Telnyx first; SignalWire, Sinch, AnveoDirect, Flowroute, Gamma and BT One Voice in the UK, Telstra SIP Connect in Australia, or another) to the built-in Asterisk engine, or fax through your office's Avaya IP Office or Aura phone system on the local network. Fax over T.38 by the minute with no per-page fee, and keep a record of every call. See SIP trunk setup and Avaya IP Office and Aura.
- Choose delivery routes and track spending. Configure additional outbound routes, rate cards (including flat monthly plans), and destination preferences. Faxbot uses price estimates and delivery history to rank routes, records each attempt, and reconciles reported SignalWire charges and, with a
TELNYX_API_KEY, what Telnyx billed for each sent and received trunk call, separately from delivery status. Unknown charges stay unknown and a route with an unknown cost is never called the cheapest. A sent fax or received call with no charge and no estimate (for example an answered call whose length was never reported) is left out of every total and counted as "not priced yet" beside it, never as $0. See delivery routes. - Use the price for the number actually called. Recipient recommendations and attempt estimates use the account's applicable destination tariff, including approved alternate numbers and prices entered for where calls start. A domestic rate does not stand in for a missing international rate. A monthly allowance applies only where its tariff covers the call; a separately priced international fax is not labeled included.
- Compare setup plans. In Savings & optimization → Facts to establish, compare up to ten setup items under your stated currency, spending limit and time period. Enter shared costs and expected and cautious running-cost reductions; Faxbot finds the best affordable group or recommends keeping what is installed. The inputs are not saved and the plan changes no routes or partner enrollments.
- Deliver incoming documents by email. One intake queue collects ordinary faxes and direct deliveries. SMTP connectors send the received PDF to configured inboxes, with retries for confirmed temporary failures and review for uncertain outcomes. See intake.
- Hand received documents to an owner.
Faxes → Received and
faxbot faxes received ownersgive each received document an owner who acknowledges it and marks it done, with an optional operational acknowledgement target per installation or mailbox, one escalation to a backup person, and a per-item evidence export. An owner must already be able to see the document; assignment never grants access. See Owners in Received. - Send directly to verified Faxbot partners. Enrolled installations can exchange encrypted original PDFs, or the exact fax image unless the receiving partner turns that off, and signed receipts using the recipient's usual fax number, with no telephone call. Every direct arrival is filed as a received fax with an owner. Enrollment requires both installations and a fax challenge; ordinary fax fallback preserves the delivery's identity and uncertainty checks. See direct delivery.
- Send short faxes to one number together. When a recipient agrees, faxes to its number can wait a few minutes and share one SIP trunk call, which saves per-call minimums. See sending together.
- Notice the fax that never came.
Faxes → Expected and
faxbot faxes expectedrecord a fax before it arrives: its reference (such as PO 483), what should come, from whom and by when. Faxbot closes it only when a received fax carries that exact reference in its subaddress, a partner's registered form, a Direct message it answers or an email subject pattern you set; a fax from a known number, partner or address is only proposed for you to confirm. Open work can be imported from another system's CSV or JSON export, and after that system's outage the next export is sorted into already done, new and held for you. See Expected faxes. - Avoid repeating acknowledged case documents. A case packet lists the documents a recipient has acknowledged on a one-page index and sends only new or changed ones, when an administrator records that the recipient accepts references. A delivered fax alone does not count as acknowledgement. The recipient acknowledges a document through a partner's signed receipt, the receiving team acknowledging a packet delivered to one of your own numbers, or a person recording what the recipient confirmed. Each acknowledgement is trusted for the recipient's reuse period, which is 90 days unless you set another. If the recipient cannot find a document, the next packet sends it in full, and a person can resend the whole packet as a new fax. Faxbot checks the recipient's reference setting; collecting evidence of that consent is future work. Preview packets before sending. See case packets.
- Manage people and integrations. Named users, groups, roles, mailbox permissions, scoped API keys, sessions, and mobile pairing are managed in the console. The server enforces the same permissions. See access control.
Admin Console
The API serves the console at /admin/ui/. Its left panel has six areas, each page at its own address (such as #/delivery/trunk), and Send a fax at the top for people who may send:
- Overview: what Faxbot is doing for you (the capabilities that acted on your faxes and the results, each in its own unit), the next improvements, everyday faxes with Send a fax, and what needs a person now, grouped by the action it needs and each opening its exact list; a serious problem moves to the top while it lasts. At the bottom, a map of every way Faxbot saves money, along a fax's path, with whether each is on, works here and has been tested.
- Savings & optimization: capabilities, opportunities, facts to establish, savings results (estimates), spending, charges, invoices, and prices and plans.
- Faxes: Received (with each fax's owner), Sent (route, cost, delivery attempts), Send a fax (route and cost before sending), Expected, Forms and Case packets.
- Delivery setup: under Numbers & mailboxes, every number Faxbot carries, mailboxes, number moves, blocked senders and sending identity; under Documents in and out, staff email delivery and the email and folders that bring documents in; under Connections, the providers and accounts in use, routing rules, one page per provider in use (the trunk named by its carrier), and Add or change a provider, which opens the Setup wizard.
- Recipients: the numbers you fax and their route order, and direct-delivery partners.
- Administration: under People & access, users, groups, roles, who has access, keys and phones, and sessions; under Installation, setup, security, documents and retention, AI analysis and the NPI record; under Monitoring, system health, the audit log and logs; and Developer (API and SDKs, AI assistants, terminal, scripts and checks, provider plugins).
Every address from before the six areas still opens the page that does that job now, with its query, and says once where the page moved from. An address that names no page, or a page you may not open, shows its own short message instead.
Screens follow the signed-in user's permissions, use plain words outside Developer, and show settings only the owner may change disabled to everyone else. See the console guide and Setup Wizard.
Quick start with Docker Compose
-
Copy the bootstrap configuration:
sh cp .env.example .env -
Replace the example credentials, set a strong installation
API_KEY, and choose a provider using its setup guide. For an initial document-only evaluation, setFAX_DISABLED=truebefore the first startup: jobs remain held and are not reported as successful transmissions. - Set the public URL and console origins for your deployment. Console sessions require HTTPS. For an HTTP-only Docker evaluation on a trusted private network, explicitly set
FAXBOT_ALLOW_INSECURE_HTTP_SESSIONS=true; see authentication for the transport requirements. - Build and start the API and console:
sh docker compose up -d --build api
SIP/Asterisk installations also need the asterisk service and a configured trunk; follow the Asterisk guide.
- Open
http://localhost:8080/admin/ui/for a local HTTP evaluation, or/admin/ui/on your configured HTTPS address. Sign in with the installation key to create the first owner, then use a named account for daily work.
Health checks are available at /health and /health/ready. /health/ready answers 200 when Faxbot is ready for what it is set up to do (sending, receiving or both) and 503 otherwise, the same rule faxbot admin health uses for its exit code. Readiness does not prove that a fax has been delivered. Faxbot starts even when it cannot sign in to its fax engine (Asterisk): readiness, the dashboard and Settings give the reason in one sentence, sends are refused with it, and Faxbot keeps trying. The Compose file restarts the api and asterisk services after any exit, including Restart Faxbot in the console.
Credentials in .env (provider keys, passwords and secrets) are read at every start and are the values in force; the console shows them as Set in .env and they are changed there, followed by docker compose up -d (a plain docker compose restart keeps the old values). API_KEY (the installation key) is read only at the first start, and other settings are managed in the console after that. Follow any requested restart (Settings offers Restart now) and confirm the active settings before transmitting. Held test jobs remain held when sending is enabled later.
AI analysis
Open Administration → AI analysis to choose OpenAI, OpenRouter, or another OpenAI-compatible API. Enter the API base address, model identifier and API key, save them, and test the connection. The owner can then enable analysis and choose a refresh interval; zero means manual refresh only. Keys are encrypted with the installation's existing secret storage and are never returned in full to the console or command line.
Run analysis queues a saved report. The model can read bounded operational evidence about outbound delivery outcomes, attempt costs and calls avoided. It receives no fax documents, fax numbers or saved provider credentials. It cannot send a fax or change settings. Existing cost calculations and rule-based recommendations continue to update from records without an LLM. AI advice is additional interpretation; estimates, reported charges and settlements remain separate, and the analysis does not claim to total subscriptions, inbound charges or unmatched bills.
The console shows when analysis last completed, its model and evidence, whether it is stale, and any refresh failure. A failed refresh keeps the previous successful report. The same controls are available with faxbot admin analysis configure, test, run and status; faxbot savings analysis reads the saved report. Use --key-prompt or --key-stdin when configuring the model key. No model provider is contacted until you enable analysis or explicitly test its connection.
SDKs and AI assistants
Use the Python SDK or Node.js SDK to call Faxbot's API:```sh
pip install faxbot
npm install faxbot
Another system can hand a PDF to the work queue with `POST /imports` and a small JSON manifest; see import documents. An email mailbox or a watched folder can do the same without any code, under **Delivery setup → Email and folders** (`faxbot delivery connectors`).
Faxbot's AI assistant servers (Node and Python) work over stdio and Streamable HTTP. The Python server also offers the older SSE transport, which is removed in the next release. Remote requests use the caller's own Faxbot identity. See MCP setup and transport authentication.
## Command line
The `faxbot` command does what the Admin Console does, apart from its built-in terminal, under the same six areas: after `faxbot send` and `faxbot status` come `overview`, `savings`, `faxes`, `delivery`, `recipients` and `admin`. The command names from before the six areas (`received`, `sent`, `forms`, `expected`, `numbers`, `providers`, `costs`, `access` and `system`, and renamed commands such as `costs savings`) still work, hidden from help, so scripts keep running. Every setting can be read and changed with `faxbot admin settings`. Output is readable by default and `--json` for scripts.```
docker compose exec api faxbot admin health
FAXBOT_API_KEY=... faxbot send +15551234567 referral.pdf
With Faxbot stopped, faxbot admin recover-owner, backup, restore and migrate recover owner access, back up and restore an installation, and upgrade its database. See Command line and the command reference.
Mobile
The iOS companion connects to your Faxbot server to send faxes and check status. Pair it with a short-lived, single-use code from the console. See the iOS guide for setup and TestFlight invitations.
Documentation and development
- Release notes, including the upgrade steps.
- Getting started, deployment, and provider setup.
- API reference, access and sign-in API, and reference overview.
- Authentication, access control, and security.
- Contributing and local checks and agent instructions.
- Enterprise correspondence architecture: proposed shared workflows, configurable requirements and guided setup, with current-code gaps and acceptance criteria.
Contributions should keep the console usable, preserve provider capability checks, and update the README, roadmap, and affected operator documentation in the same change as the capability.
Reference pages under docs/generated/ are generated from code. The README/roadmap, agent instructions and planning sources are maintained separately. AI prose proposals are restricted to permitted documentation pages, including when applied locally.
Roadmap
Checked items are implemented in the current source checkout. Unchecked items are planned or require validation; they are not claims about a release date or measured savings.
Implemented
-
[x] Destination-aware prices agree across recipient recommendations, plan allowances and attempt estimates. Unknown international prices stay unknown, separate destination tariffs do not consume domestic allowances, and extra provider accounts retain their own applicable rate cards. Verified with synthetic routing, HTTP and accounting checks; this correction does not claim a joint optimizer over every document, account, batch and sending time.
-
[x] Opt-in operational AI analysis with encrypted OpenAI-compatible credentials, OpenRouter support, bounded read-only evidence tools, durable manual and scheduled refreshes, visible freshness/failure state, and matching console/CLI controls. Verified with synthetic data and mocked model responses; live model-provider validation is separate.
-
[x] Number dependency answers and checked move plans are available in Delivery setup → Number moves and
faxbot delivery numbers advice,dependenciesandmove. Record account readiness, carrier cutover and receipt tests, review evidence, and finish or abandon the plan. Faxbot does not place a port order or send a receipt-test fax automatically. -
[x] Durable outbound jobs, uncertain-outcome handling, server-side idempotency, and held test jobs.
- [x] Database validation avoids repeatedly rebuilding superseded schema descriptions. Historical upgrades, unknown-schema refusal, and all table, column and index checks remain in place.
- [x] Users, groups, roles, scoped keys, sessions, mailbox access, and single-use mobile pairing.
- [x] Cost-aware route selection, versioned rate cards, attempt costs, and separate reconciliation of the charges SignalWire, Sinch and Phaxio report for each sent fax. Sinch's and Phaxio's charges are read only once the provider says the fax is finished, with the account that sent it; a later different price is a correction, and a fax with no reported price stays unpriced, never $0 or the estimate.
- [x] Sinch Fax API as a sending route beside the SIP trunk and HumbleFax, ranked by its published $0.045 a page and then by what it really cost per delivered fax. A send Sinch refuses (key, project, balance, number or document, or a request to slow down) or that never reached Sinch fails for certain and goes by the next route with Sinch's reason; any other lost answer waits for a person and is never sent again. A Sinch failure takes another route only when no page can have arrived. The Sinch page and
faxbot delivery providers callbacksgive the exact Incoming webhook URL to paste into Sinch, from the server's public address or a separate address for Sinch, and where a user name and password go in it. Tested with simulated Sinch and Phaxio APIs; the live send, receipt and charges are pending. - [x] The Telnyx Fax API as a sending route billed by the page, so a per-page route can be measured beside the trunk (by the minute) and HumbleFax (a flat plan). Faxbot uploads the pages each attempt chose to Telnyx's media storage and sends the fax by name, so Telnyx needs no link back to the server, then checks the fax's status with Telnyx until it is done. Busy, no answer, no fax machine and anything Telnyx refuses before the call fail for certain with a plain reason and may go by another route; a dropped call or any other reason waits for a person and is never sent again, and a lost answer to the send itself waits for its fax ID. Its published price, $0.007 a page plus the call's minutes at Telnyx's US outbound SIP rate ($0.005 a minute, whole minutes; telnyx.com/pricing/fax, read 13 October 2026), is its rate card, so route choice and estimates rank it with the others. A Telnyx Fax API account, and a trunk with the Telnyx preset, that has no rate card saved in Faxbot is priced by Telnyx's published price, and the estimate says whose price it is and when Faxbot read it ("Telnyx's published price, read 3 October 2026"; both pages read again on 13 October 2026, unchanged); a price you enter for the account always wins. Before, such an account read "none of your routes had a price" and cost routing could not rank it. It uses the Telnyx API key the trunk already has. The console's Telnyx Fax API page (choose it under Add or change a provider) and
faxbot delivery providers accounts fax-applicationcreate the Fax Application in your Telnyx account and save its ID;faxbot delivery providers configure telnyx_faxandaccounts add --provider telnyx_faxset it up from the command line. With Telnyx's public key saved, Telnyx's signed results notices make Faxbot check the fax at once. Route choice prices it from its card before each send, but a sent fax's own cost stays unknown (never $0) until Faxbot reads Telnyx's records of the call's length, which is next. It does not receive faxes yet. Tested with a simulated Telnyx API only; nothing has run against a real Telnyx account yet. - [x] Your Telnyx balance, before it stops your faxes. With a Telnyx API key set (the trunk's key, which the Telnyx Fax API also uses), Faxbot reads your Telnyx balance every 15 minutes, again at once when a Fax API send fails because Telnyx turned the account off, and at once after a burst of calls the carrier refused (three SIP 404 or 403 refusals within five minutes, on the trunk's calls or the Fax API's; at most once every five minutes). When the credit available falls below the level you set (Delivery setup → Providers & accounts → Delivery routes, Warn when your Telnyx balance is below, or
faxbot delivery providers trunk balance --warn-below 10), or, left empty, below a week of your usual Telnyx spending (Faxbot's own cost records for its Telnyx routes over the last four weeks, or $5 when it has none), Overview (Needs attention and the sending board) andfaxbot overviewsay so in one sentence, such as "Your Telnyx balance is $3.10, about 4 days of your usual faxing. When it reaches $0, Telnyx stops your calls in both directions. Add funds in the Telnyx portal under Billing." At $0 or less, or when Telnyx reports the account turned off, the warning says sending and receiving through Telnyx have stopped, and Faxbot skips its Telnyx routes, so a fax goes by your next route and says why. A Fax API send Telnyx fails because the account is turned off is a certain failure before any page. On 13 October 2026 Telnyx turned an account off at -$1.38: calls to its numbers got SIP 404 and Faxbot showed nothing. Tested with a simulated Telnyx balance answer only. - [x] Telnyx charges for every trunk call, sent and received: matched by SIP Call-ID or by a unique number-and-time match (ambiguous records stay unmatched and are counted; a full page of records without a page count is never taken as the whole window; a call settles only once every record matched to it is priced; a record Telnyx still has not priced a week after the call settles the call with that part marked never priced, so the fax reads "Telnyx charged $0.005 for part of this call and never priced the rest, so its full cost is unknown." and counts as never priced in full, never as the priced part alone. The week is Faxbot's own limit, because Telnyx documents no time by which a price is final (read 6 October 2026)), kept with corrections and never changing delivery; shown per route in Spending, in Sent's fax details and in Received, and with
faxbot savings spending,reconcileandfax. Calls Telnyx billed that Faxbot has no record of (such as a received fax whose hand-over failed) count in spending on their own line and attach to the received fax when exactly one matches. Route recommendations never call an unknown cost the cheapest; a flat plan reads "Included in your HumbleFax plan ($10 a month)." and counts its fee once per 30 days. Each provider in use gets its published price (Phaxio, Sinch, SignalWire, HumbleFax, SIP trunk carriers; read 2026-10-03) as an editable rate card on start, and the Overview reads the same spending as Costs. Spending, the Overview andfaxbot savings spendingcount faxes and calls with no price apart ("2 faxes and 1 call not priced yet") instead of adding them as $0, and calls the carrier never priced in full apart from those ("1 call never priced in full"; only its priced part is in the total). (Live on 3 October 2026: the sent calls' $0.01 and $0.005 and a received call's $0.0032 showed against the right faxes. Matching by the captured SIP Call-ID and the unrecorded-call sweep are tested with synthetic records only.) - [x] Charges from every source Faxbot can read, and monthly invoices for the rest (Savings & optimization → Charges and Savings & optimization → Invoices,
faxbot savings charges [sweep]andfaxbot savings invoices add · list · show, migration 0051): - Received faxes: what Sinch and Phaxio charged for each fax they received, read with the account the fax came in on (never another account's key or project), kept with corrections, and shown in Received. Savings & optimization → Spending, the Overview and
faxbot savings spendinggive each cloud provider its own received line, apart from the trunk's calls ("Received faxes: Sinch $0.42 for 6 faxes"), with estimates from the receiving price where nothing was reported and a flat plan's faxes as included. A fax with no price is counted as not priced yet, never $0. - Faxes Faxbot has no record of: Faxbot lists each Sinch, Phaxio and SignalWire account's faxes and shows any it has no record of ("Sinch billed a fax to +1… on 3 Oct that Faxbot didn't send"). This catches a fax sent from the provider's own website or one whose record was lost. It is read only: Faxbot never sends, fetches or changes those faxes. A sent fax near a fax Faxbot was unsure about says it may be that fax. HumbleFax, eFax and Documo publish no such list, and the page says so.
- Other trunk carriers: SignalWire call records (Calls API) and Flowroute's call-record export feed the same per-call charge as Telnyx, with
FLOWROUTE_ACCESS_KEYandFLOWROUTE_SECRET_KEYon the Flowroute trunk page. Gamma, BT One Voice and Telstra SIP Connect publish no call-record API that Faxbot could find (searched 8 October 2026), and their trunk pages send you to Savings & optimization → Invoices instead. - Invoices (M27): enter each account's monthly invoice total, optionally with the invoice file. Faxbot shows the part your faxes don't explain ("$3.20 of your HumbleFax invoice for September 2026 isn't explained by your faxes"), itemized as plan fee, allowance overage, unused commitment, reported charges, estimates and faxes Faxbot has no record of. A month with an unpriced fax reads as incomplete. When the residual recurs (at least $1 and 5%, the same way, in two of the account's last three invoices whose months are complete), Faxbot says which price to check. A corrected total is a new version, and the earlier one is kept.
- Tested with simulated Sinch, Phaxio, SignalWire and Flowroute answers shaped like their documented responses. None of it has run against a real account yet.
- [x] Shared intake queue and SMTP email delivery, with console management. Each delivered email keeps the addresses the email server accepted, at that moment; Faxes → Received,
faxbot faxes received deliveries listand the evidence export name them, and say plainly when an email from before migration 0022 has none recorded. They never show the connector's addresses today in their place. - [x] Enrolled direct partners, encrypted original-PDF delivery, signed receipts, and controlled fax fallback.
- [x] Recipient-approved case packets, accepted-document history, and preview, in the console (Faxes → Case packets, with the recent cases listed) and through the API (
GET /cases). - [x] Case documents carry their source, version and purpose. The same file sent for another purpose, or labelled as a newer version, is a separate entry. Fax success makes a document "delivered". It becomes "acknowledged" only through a partner's signed receipt, the receiving team acknowledging a packet delivered to one of your own numbers, a received acknowledgement fax, or a person's note. Acknowledgements expire after each recipient's reuse period (90 days unless set; it can also be unlimited). "Recipient couldn't find it" sends a document in full next time. Repair: send the full packet resends every kept original as a new fax, for a reason a person records; Faxbot never does this on its own. Kept originals follow Keep sent fax files in Storage & retention: the cleanup removes one once it has not been added or sent for that long, and a repair names each document retention removed. All of this is in Faxes → Case packets and
faxbot faxes cases accept · invalidate · reuse · repair. Tested with synthetic data on SQLite and PostgreSQL, including the 188-to-56-page case example from the research. No real recipient has acknowledged a packet yet. - [x] Case packets built from a recipient's checklist. A checklist lists document types, a version and a "dated within N days" limit for each, and whether each is required. Checklists are versioned and never change once saved. Faxbot picks from the originals kept in the case the same way every time and gives a reason for each pick, then lists the missing items. A person checks the selection before it is sent, and a required item can be left out only when the person says the recipient agreed. Suggestions for missing items compare titles and stay off unless the owner turns them on; no language model is connected. This is in Faxes → Case packets → Build a packet from a checklist and
faxbot faxes cases add · originals · build · checklist · suggestions, with one synthetic example checklist. Real forms' checklists belong to integrations.
…(正文过长,页面只展示前面部分,完整内容见仓库)