Skip to content

Setup Wizard

New to fax? Start here. This wizard gets you sending in minutes and explains each choice in plain language, with direct links to the third‑party pages you’ll need.

Backends Guide Security Docs

What you’re choosing

  • Phaxio by Sinch (cloud): A developer fax API (Phaxio is part of Sinch). Simple and reliable. Two flavors in Faxbot:
  • “Phaxio” flow: Phaxio fetches your PDF from your server via a public URL. Best if you already have a domain or can run a tunnel. Supports webhooks to update status.
  • “Sinch (Direct Upload)”: Faxbot uploads the PDF directly to Sinch. Best if you do not have a public URL or domain yet. Send-only works without webhooks.
  • Documo mFax (cloud): Direct upload to Documo. No domain/tunnel required. Good beginner option alongside Sinch.
  • SIP / Asterisk (self‑hosted): No third‑party cloud, uses your SIP trunk. More advanced; skip for now if you’re just getting started.
  • Best when you already have a public HTTPS URL or can run a tunnel.
  • Webhooks update status; HMAC verification is on by default.
  • HIPAA‑friendly with a BAA.
FAX_BACKEND=phaxio
PHAXIO_API_KEY=...
PHAXIO_API_SECRET=...
PUBLIC_API_URL=https://yourdomain.example
PHAXIO_CALLBACK_URL=https://yourdomain.example/phaxio-callback
PHAXIO_VERIFY_SIGNATURE=true
  • Fastest “no‑domain” option; send‑only works without webhooks.
  • Credentials live in your Sinch project.
FAX_BACKEND=sinch
SINCH_PROJECT_ID=...
SINCH_API_KEY=...
SINCH_API_SECRET=...
# Optional regional override
# SINCH_BASE_URL=https://us.fax.api.sinch.com/v3
  • No domain required; direct upload to Documo.
  • Optional sandbox for evaluation.
FAX_BACKEND=documo
DOCUMO_API_KEY=...
# DOCUMO_SANDBOX=true
  • Self‑hosted telephony; requires SIP trunk + AMI.
  • PDF→TIFF conversion; result events via AMI.
FAX_BACKEND=sip
ASTERISK_AMI_HOST=asterisk
ASTERISK_AMI_PORT=5038
ASTERISK_AMI_USERNAME=api
ASTERISK_AMI_PASSWORD=change_me

v3

The wizard writes safe defaults and can export a ready‑to‑use .env. You can optionally persist the .env on the server from Settings.

Do I need a domain?

  • No, if you pick “Sinch (Direct Upload)”. You can send faxes without any public URL.
  • Yes (or a tunnel) if you pick “Phaxio” and want status callbacks or if Phaxio must fetch your PDF from your server.
  • You can always add a domain later. For quick tests, use the included tunnel script: scripts/setup-phaxio-tunnel.sh.

Beginner 5‑minute path (no domain required)

  1. Choose backend: “Sinch (Direct Upload)”.
  2. Create a Sinch/Phaxio account:
  3. Sign up: https://dashboard.sinch.com/signup (this is where Phaxio signups redirect — that’s normal).
  4. After signup, create a project, then get your Project ID and API key/secret.
  5. In the wizard, paste:
  6. Project ID → SINCH_PROJECT_ID
  7. API key → SINCH_API_KEY
  8. API secret → SINCH_API_SECRET
  9. Click “Apply”. Then send a test fax in the Admin Console or via curl.

Alternative: Documo (no domain required)

  1. Choose backend: “Documo (mFax)”.
  2. Create an account and API key:
  3. Sign up: https://www.mfax.io/pricing
  4. Enable API and create an API key in the Documo web app.
  5. Docs: https://docs.documo.com
  6. In the wizard, paste:
  7. API key → DOCUMO_API_KEY
  8. Optional: enable sandbox → DOCUMO_SANDBOX=true
  9. Click “Apply”, then send a test fax. No public URL is required for sending.

If you have a domain (or can run a temporary tunnel)

  1. Choose backend: “Phaxio (Recommended)”.
  2. Create an account and get credentials:
  3. Phaxio site: https://www.phaxio.com → Sign Up takes you to Sinch (expected).
  4. Direct signup: https://dashboard.sinch.com/signup
  5. Get: PHAXIO_API_KEY and PHAXIO_API_SECRET (same as Sinch API key/secret in many accounts).
  6. Official Phaxio docs: https://www.phaxio.com/docs/
  7. Make your API reachable over HTTPS:
  8. Option A: use your domain, e.g. https://api.yourdomain.com
  9. Option B: quick test tunnel → run scripts/setup-phaxio-tunnel.sh to get a temporary https://...trycloudflare.com URL.
  10. In the wizard, set:
  11. PUBLIC_API_URL to your HTTPS URL
  12. PHAXIO_CALLBACK_URL to https://YOUR_URL/phaxio-callback
  13. Paste your API key/secret
  14. Click “Apply”, then send a test fax. Status updates arrive via callback (HMAC verified by default).

Security profile

  • HIPAA (strict): requires API key for your Faxbot API, enforces HTTPS, enables audit logging, verifies provider signatures.
  • Non‑PHI (convenience): relaxed defaults for local/dev; you can switch to HIPAA later without changing providers.

What is Phaxio? What is Sinch?

  • Phaxio is a developer‑focused fax API. It’s part of Sinch now. When you click “Sign Up” on phaxio.com, you’ll be redirected to a Sinch signup page — that is expected. Your credentials work with Faxbot’s Phaxio flow and the Sinch (direct upload) flow.

Where do I find credentials?

Apply & reload

  • “Apply” writes settings to the running API with safe defaults.
  • “Generate .env” gives you a copy‑ready file. If enabled, “Save .env to server” writes it for persistence.

Helpful tips

  • No domain? Pick “Sinch (Direct Upload)” and you can send immediately.
  • For Phaxio tests without a domain, run: scripts/setup-phaxio-tunnel.sh (uses Cloudflare Tunnel; falls back to ngrok if installed).
  • If a change affects persistent connections (e.g., Asterisk AMI), you’ll be prompted to restart the API.
  • Secrets are not stored in plugin manifests; they live in environment variables.

Example .env snippets

  • Phaxio (HIPAA profile) 
    FAX_BACKEND=phaxio
PHAXIO_API_KEY=... 
PHAXIO_API_SECRET=...
PUBLIC_API_URL=https://yourdomain.example
PHAXIO_CALLBACK_URL=https://yourdomain.example/phaxio-callback
PHAXIO_VERIFY_SIGNATURE=true
API_KEY=generate_a_strong_key
ENFORCE_PUBLIC_HTTPS=true
AUDIT_LOG_ENABLED=true
PDF_TOKEN_TTL_MINUTES=60
  • Sinch (direct upload) 
    FAX_BACKEND=sinch
SINCH_PROJECT_ID=...
SINCH_API_KEY=...
SINCH_API_SECRET=...
# Optional regional override
# SINCH_BASE_URL=https://us.fax.api.sinch.com/v3
API_KEY=generate_a_strong_key
  • SIP/Asterisk (self‑hosted) 
    FAX_BACKEND=sip
ASTERISK_AMI_HOST=asterisk
ASTERISK_AMI_PORT=5038
ASTERISK_AMI_USERNAME=api
ASTERISK_AMI_PASSWORD=change_me
FAX_LOCAL_STATION_ID=+15551234567
FAX_HEADER=Faxbot
API_KEY=generate_a_strong_key

Warnings and prompts

  • Missing HTTPS on PUBLIC_API_URL with cloud backends → warning with quick‑fix link to the tunnel script.
  • Empty API_KEY in production → prompt to enable auth.
  • Ghostscript not found for SIP/Asterisk → warn that conversion/pages may be stubbed.

Learn more

Quick test (optional)

  • Use Admin Console → Send Fax to queue a test after applying settings.
  • Attach a small PDF or TXT (≤10 MB).
  • Watch status on Jobs; callbacks update status for Phaxio when reachable.

Tab anchors

You can right‑click a tab to copy a direct link to it. For example, link to the “Sinch (Direct Upload)” tab with #sinch-direct-upload.

# assumes API_KEY is enabled; replace placeholders
BASE="http://localhost:8080"
curl -X POST "$BASE/fax" \
  -H "X-API-Key: $API_KEY" \
  -F to=+15551234567 \
  -F file=@./document.pdf

# check status later
curl -H "X-API-Key: $API_KEY" "$BASE/fax/$JOB_ID"