Send a fax

Faxprogrammable fax

A fax is sent from a document URL and its status webhook reports pages and result.

fax

The claim

Fax is one REST call, POST .../Faxes with To, From and a MediaUrl pointing at a PDF, followed by a wait. Transmission takes minutes and can fail half-way, so the outcome (delivered with NumPages, or failed with an ErrorCode) arrives at StatusCallback; the create response only says queued.

How it works

client.compat.faxes.create(To=to, From=FROM, MediaUrl=pdf_url, Quality="fine",
                           StatusCallback=f"{PUBLIC_URL}/fax-status")

The send goes through the Compatibility API’s Faxes endpoint (/api/laml/2010-04-01/Accounts/<project>/Faxes). There is no native /api/fax send; the native surface has fax logs (GET /api/fax/logs) for reconciliation. From inside a call the same operation is the SWML verb send_fax; over RELAY it is call.send_fax. Non-final statuses (queued, processing, sending) are ignored by the handler; final ones are recorded.

What to change first

Point MediaUrl at a document your own app generated a minute earlier, and retry on busy or no-answer with a backoff, because the fax world still has both.

Where this sits

Before this

Buy a number and point it at your app

Receive an inbound fax

python/app.py

"""Send a fax.

A fax is sent from a document URL with one REST call to the Compatibility Faxes
endpoint. Delivery takes minutes and the outcome - pages sent, or a failure -
arrives on StatusCallback, not in the create response.

Written against signalwire-sdk 3.0.1 (RestClient.compat.faxes) and Flask.
"""
import os

from dotenv import load_dotenv
from flask import Flask, request
from signalwire.rest import RestClient

# the SDK does not read .env for you
load_dotenv()

app = Flask(__name__)
client = RestClient()

FROM = os.getenv("SIGNALWIRE_FAX_NUMBER", "+15550001111")
PUBLIC_URL = os.getenv("PUBLIC_URL", "https://your-host.example.com")

FINAL = {"delivered", "failed", "no-answer", "busy", "canceled"}
outcomes = {}


def send(to, media_url, quality="fine"):
    """Queue the fax. Returns the fax sid; the result comes to /fax-status."""
    fax = client.compat.faxes.create(
        To=to,
        From=FROM,
        MediaUrl=media_url,          # a publicly fetchable PDF
        Quality=quality,
        StatusCallback=f"{PUBLIC_URL}/fax-status",
    )
    return fax.get("sid")


@app.post("/fax-status")
def fax_status():
    f = request.form
    sid, status = f.get("FaxSid"), f.get("FaxStatus")
    if status in FINAL:
        outcomes[sid] = {"status": status, "pages": f.get("NumPages"),
                         "error": f.get("ErrorCode")}
    return "", 204


if __name__ == "__main__":
    app.run(port=int(os.getenv("PORT", "8080")))

Run it

cd python
pip install -r requirements.txt
export SIGNALWIRE_SPACE=... SIGNALWIRE_PROJECT_ID=... SIGNALWIRE_API_TOKEN=... SIGNALWIRE_FAX_NUMBER=+1555... PUBLIC_URL=https://<your-host>
python app.py
python -c "import app; print(app.send('+1555...', 'https://<public-url>/document.pdf'))"

Verify it

python verify.py          # from the recipe folder, not python/

With the HTTP layer recorded, send() must make one documented POST with the required To, From, MediaUrl and a StatusCallback, checked against tools/openapi/compat.json. The status webhook must record only final statuses, with page count or error code.

Report an issue